[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M756VWSGZDP9GSGD2V79TBA6":3,"skill-same:01M756VWSGZDP9GSGD2V79TBA6":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M756VWSGZDP9GSGD2V79TBA6","agents",null,"Imported from AGENTS.md","itaywol\u002Fadeptability","itaywol","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6410154?v=4","01M756SKJABTDMYHWVMHBA0M6E","Itay Wolfish","01M756SKKJFSV073PS3KYR896D",9,"MIT","https:\u002F\u002Fgithub.com\u002Fitaywol\u002Fadeptability\u002Fblob\u002Fmain\u002F.adeptability\u002Fstaging\u002F.claude\u002Fskills\u002Fagents\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: agents\ndescription: Imported from AGENTS.md\n---\n\n\n# AGENTS.md\n\nGuidance for AI coding agents working on the **adeptability** (`adept`) codebase.\nHumans: see [README.md](README.md) for usage and [CONTRIBUTING.md](CONTRIBUTING.md) for the contributor workflow.\n\n## Project Overview\n\n`adept` is a single-binary Go CLI for **cross-harness AI skill portability**: you author a\nskill once in a canonical format and `adept` renders it accurately into every AI coding\nharness in your project — Claude Code, Cursor, Codex, GitHub Copilot, OpenCode, and any\nconfig-driven adapter you register — then keeps the two sides in sync in both directions.\n\n- **Language:** Go 1.25, [Cobra](https:\u002F\u002Fgithub.com\u002Fspf13\u002Fcobra) command surface.\n- **Module:** `github.com\u002Fitaywol\u002Fadeptability`. Binary: `adept` (entrypoint `cmd\u002Fadept`).\n- **No runtime services.** Everything is local filesystem + `git` + optional network\n  (GitHub API, skills.sh, an LLM provider for the optional intent pass).\n- **Source of truth is the filesystem.** Content hashes — not version numbers — drive every\n  sync decision. There is no central database.\n\n## Commands\n\nUser-facing CLI (five verbs + three subcommand groups):\n\n| Command | Description |\n| --- | --- |\n| `adept init [--from \u003Curl>] [--ref \u003Cbranch>] [--name \u003Clocal>] [--mode symlink\\|copy]` | Scaffold `.adeptability\u002F`, optionally clone a library, adopt existing harness files |\n| `adept status` | Project state at a glance: init, libraries, harnesses, drift |\n| `adept sync [--harness \u003Cid>] [--force] [--dry-run]` | Push canonical skills → every enabled harness |\n| `adept sync-from [--harness \u003Cid>] [--all] [--force] [--dry-run]` | Adopt harness-side edits back into canonical |\n| `adept diff [--harness \u003Cid>]` | Show drift between canonical and rendered output |\n| `adept harness {add\\|remove\\|list}` | Manage enabled harnesses |\n| `adept skill {add\\|install\\|update\\|info\\|search\\|check\\|edit\\|remove\\|list}` | Manage canonical skills (local + skills.sh\u002FGitHub) |\n| `adept library {add\\|remove\\|list}` | Manage remote skill-library remotes |\n| `adept config {list\\|get\\|set\\|unset\\|llm ...}` | Strict-typed project config |\n\nGlobal flags: `--json`, `--log-level debug|info|warn|error`, `--project \u003Cpath>`, `--library \u003Cpath>`.\nRun `adept \u003Ccmd> --help` for the authoritative, always-up-to-date surface.\n\n## Architecture\n\n```\ncmd\u002Fadept\u002F            main(): injects build info, calls cli.NewRoot, maps errors→exit codes\ninternal\u002Fcli\u002F         Cobra composition root. One file per command group. NO package state.\npkg\u002Fadept\u002F            STABLE public types + interfaces + sentinel errors (no behavior here)\npkg\u002Fadeptschema\u002F      embedded JSON Schemas (skill \u002F adapter \u002F org \u002F config) for validation\ninternal\u002Fcanonical\u002F   parse skill.yaml & SKILL.md frontmatter → *adept.Skill, schema-validate\ninternal\u002Frender\u002F\u003Ch>\u002F  one package per built-in harness: Renderer + Import (reverse render)\ninternal\u002Fadapter\u002F     config-driven (YAML) harness adapters: load, validate, synthesize\ninternal\u002Fharness\u002F     orchestrator: sync \u002F sync-from \u002F drift detection across all harnesses\ninternal\u002Fmerge\u002F       3-way merge + diff3 for sync-from conflict handling\ninternal\u002Flibrary\u002F     centralized + multi-library skill resolution (first-wins on collision)\ninternal\u002Fscan\u002F        static safety scanner (+ optional LLM intent pass)\ninternal\u002Fregistry\u002F    github (trees API) + skillssh (skills.sh catalog) clients\ninternal\u002Fgit\u002F         git clone\u002Fpull\u002Fcheckout-at-SHA wrapper\ninternal\u002F{fsutil,locks,hash,config,project,log,budget,org}\u002F  supporting primitives\n```\n\n### Core invariants — do not break these\n\n1. **`pkg\u002Fadept` holds types, not behavior.** It must stay dependency-light (import-free\n   where possible — e.g. `SkillIDPattern` is a string, compiled in `internal\u002Fcanonical`).\n   In-process consumers (tests, future LSP\u002Fplugins) depend on it; keep it stable.\n2. **Composition root, no globals.** `cli.NewRoot` wires every concrete implementation\n   behind an interface into a `*Deps` container. No package-level state, no `init()` side\n   effects. Every command takes its dependencies explicitly so it can be unit-tested with\n   mocks. Add a new dependency by extending `Deps`, not by reaching for a singleton.\n3. **Identity is `(id, content-hash)`.** Skills carry no version field; the hash is the\n   answer to \"did this change\". Do not introduce version numbers as a sync signal.\n4. **Canonical layout:** a skill is a directory `\u003Croot>\u002Fskills\u002F\u003Cid>\u002F` with one `SKILL.md`\n   (YAML frontmatter + markdown body) plus optional sidecars (`scripts\u002F`, `references\u002F`,\n   `assets\u002F`). The directory name is the authoritative id. Skill ids use the\n   harness-compatible charset `^[a-z0-9](?:[a-z0-9-]{0,48}[a-z0-9])?$` (no underscore).\n   Per-skill, per-harness overrides live in an optional `harness:` map (keyed by harness id)\n   plus a promoted `model` field; renderers merge their entry last via `common.MergeOverride`,\n   and the schema forbids overriding identity fields. Currently consumed by claude-code and cursor.\n5. **Harness models differ — renderers must respect them:** per-skill (Claude, OpenCode),\n   single-file (Cursor — drops sidecars), and aggregator (Codex\u002FCopilot — concatenate into\n   one file with section markers under a byte budget). Aggregators must parse their own\n   markers on `Import` and degrade to a single synthesized skill when markers are absent.\n6. **Secrets never touch disk.** `config.json` records *which* LLM provider\u002Fmodel is used;\n   API keys are resolved from the environment (`ANTHROPIC_API_KEY`) at call time only.\n\n### Exit codes (see `cli.ExitFromError`)\n\n- `0` clean · `1` generic error · `2` dirty\u002Fdrift (`ErrDirty`) or merge conflict (`ErrMergeConflict`).\n- Safety scan worst-severity maps to the same scheme: `clean`\u002F`low`\u002F`medium` → 0, `high` → 1, `critical` → 2.\n\n## Key Integration Points\n\n- **`pkg\u002Fadept`** — `HarnessAdapter`, `Renderer`, `Skill`, `RenderOutput`, `DriftReport`,\n  `ImportedSkill`, sentinel errors (`ErrSkillNotFound`, `ErrMergeConflict`, …), on-disk\n  layout constants (`BaseDirName`, `SkillsDirName`, …). Start here to understand contracts.\n- **`pkg\u002Fadeptschema\u002F*.schema.json`** — embedded JSON Schemas. Changing a canonical field\n  means updating the schema *and* the Go struct tags in `pkg\u002Fadept` together.\n- **`internal\u002Fcli\u002Fdeps.go`** — the `Deps` wiring. New commands are constructed from `Deps`.\n- **`testdata\u002F` golden fixtures** under each `internal\u002Frender\u002F\u003Ch>\u002F` package pin exact output.\n\n## Development\n\n```bash\ngo build .\u002F...                 # build everything\ngo build -o \u002Ftmp\u002Fadept .\u002Fcmd\u002Fadept   # build the binary\ngo test .\u002F...                  # fast tests\ngo test -race .\u002F...            # race detector (CI gate)\ngo test -run E2E .\u002Fcmd\u002Fadept   # end-to-end (builds the binary, drives real commands)\ngo vet .\u002F...\ngofmt -l .                     # must print nothing\ngolangci-lint run              # config in .golangci.yml\n```\n\n### Dogfooding\n\nThis repo is itself an adept skill library — committed skills live in `skills\u002F`, and the\nproject-canonical layout (`.adeptability\u002F`, `.claude\u002F`) is **regenerated on demand and\ngitignored**. To regenerate and verify rendering locally:\n\n```bash\nadept init --from \"$(git rev-parse --show-toplevel)\" --name adept --mode copy\nadept harness add claude-code\nadept sync\nadept status\n```\n\n## Code Style\n\n- **Formatting:** `gofmt` + `goimports`. CI fails on any unformatted file — run `gofmt -w .`\n  before committing. There is no separate formatter to learn.\n- **Linting:** `.golangci.yml` enables `errcheck`, `staticcheck`, `govet`, `gocritic`,\n  `revive` (exported symbols need doc comments), `errorlint`, `nilerr`, `bodyclose`,\n  `prealloc`, `unconvert`, `misspell`, and more. Run `golangci-lint run` locally.\n- **Errors:** wrap with context — `fmt.Errorf(\"doing X: %w\", err)`. Compare with\n  `errors.Is` against the sentinels in `pkg\u002Fadept\u002Ferrors.go`; add a new sentinel there\n  rather than matching on error strings. Never silently drop an error that loses data.\n- **Naming & shape:** small, single-responsibility functions; prefer early returns over\n  deep nesting; doc comments on every exported symbol (full sentences, starting with the\n  symbol name).\n- **Commits:** [Conventional Commits](https:\u002F\u002Fwww.conventionalcommits.org\u002F). Release-please\n  derives the next semver from the types (`feat` → minor, `fix`\u002F`perf` → patch,\n  `feat!`\u002F`BREAKING CHANGE:` → major; `refactor`\u002F`docs`\u002F`chore`\u002F`test`\u002F`ci` → no bump).\n\n## Testing\n\n- **Table-driven tests** are the default. Use `testify\u002Frequire` for assertions.\n- **Golden fixtures** live in `testdata\u002F` beside each renderer; they pin exact rendered\n  bytes. When you intentionally change output, update the fixture in the same commit and\n  explain why in the message.\n- **E2E** (`cmd\u002Fadept\u002F*_test.go`) builds the real binary and drives commands against temp\n  dirs with an isolated `HOME` and `ADEPT_LIBRARY`. Guard slow paths with\n  `if testing.Short()`.\n- **Coverage gates:** keep `internal\u002Frender`, `internal\u002Fstatus`, `internal\u002Fbudget`, and\n  `internal\u002Fcanonical` at ≥80%. Tests should catch regressions, not pad coverage.\n\n## Adding a harness\n\n**Built-in (Go) adapter** — for harnesses needing custom logic:\n\n1. Implement `adept.HarnessAdapter` in `internal\u002Frender\u002F\u003Cid>\u002F`.\n2. Add golden fixtures under that package's `testdata\u002F`.\n3. Register it in `internal\u002Fcli\u002Fdeps.go` (`registerBuiltinAdapters`).\n4. Document it in the README harness table.\n\n**Config-driven adapter** — for harnesses expressible declaratively (no code, no rebuild):\n\nDrop a `\u003Cid>.yaml` adapter in `~\u002F.adeptability\u002Fadapters\u002F` matching\n`pkg\u002Fadeptschema\u002Fadapter.schema.json` (`kind` = `per-skill` | `aggregator-single` |\n`aggregator-per-glob`, plus `output`, `frontmatter`, `body`, `detect`, `import` hints).\n\n## Publishing\n\n- **Versioning:** `release-please` opens\u002Fmaintains a release PR from Conventional Commits;\n  merging it tags `vX.Y.Z`.\n- **Release:** the tag triggers `goreleaser` (cross-compiled archives for darwin\u002Flinux\u002Fwindows\n  × amd64\u002Farm64), `checksums.txt`, cosign signing, and build-provenance attestation via\n  `actions\u002Fattest-build-provenance` (immutable-release safe). Docker publish to GHCR is opt-in\n  via the `DOCKER_PUBLISH` repo variable.\n- **Distribution (live):** GitHub release tarballs, `go install`, the `scripts\u002Finstall.sh`\n  curl installer, Homebrew tap (`itaywol\u002Fhomebrew-tap`), and GHCR images.\n- **Distribution (not wired yet):** Scoop, WinGet, and the npm wrapper (`scripts\u002Fnpm\u002F`,\n  `@itaywol\u002Fadeptability`) are unpublished — tracked in the \"additional package managers\"\n  issue, gated on a thumbs-up before we commit to maintaining them.\n- Do not hand-edit `CHANGELOG.md`, `.release-please-manifest.json`, or version strings;\n  release-please owns them.\n\n\u003C!-- gitnexus:start -->\n# GitNexus — Code Intelligence\n\nThis project is indexed by GitNexus as **adeptability** (3310 symbols, 11238 relationships, 248 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.\n\n> Index stale? Run `node .gitnexus\u002Frun.cjs analyze` from the project root — it auto-selects an available runner. No `.gitnexus\u002Frun.cjs` yet? `npx gitnexus analyze` (npm 11 crash → `npm i -g gitnexus`; #1939).\n\n## Always Do\n\n- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `impact({target: \"symbolName\", direction: \"upstream\"})` and report the blast radius (direct callers, affected processes, risk level) to the user.\n- **MUST run `detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: `detect_changes({scope: \"compare\", base_ref: \"main\"})`.\n- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.\n- When exploring unfamiliar code, use `query({query: \"concept\"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.\n- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `context({name: \"symbolName\"})`.\n\n## Never Do\n\n- NEVER edit a function, class, or method without first running `impact` on it.\n- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.\n- NEVER rename symbols with find-and-replace — use `rename` which understands the call graph.\n- NEVER commit changes without running `detect_changes()` to check affected scope.\n\n## Resources\n\n| Resource | Use for |\n|----------|---------|\n| `gitnexus:\u002F\u002Frepo\u002Fadeptability\u002Fcontext` | Codebase overview, check index freshness |\n| `gitnexus:\u002F\u002Frepo\u002Fadeptability\u002Fclusters` | All functional areas |\n| `gitnexus:\u002F\u002Frepo\u002Fadeptability\u002Fprocesses` | All execution flows |\n| `gitnexus:\u002F\u002Frepo\u002Fadeptability\u002Fprocess\u002F{name}` | Step-by-step execution trace |\n\n## CLI\n\n| Task | Read this skill file |\n|------|---------------------|\n| Understand architecture \u002F \"How does X work?\" | `.claude\u002Fskills\u002Fgitnexus\u002Fgitnexus-exploring\u002FSKILL.md` |\n| Blast radius \u002F \"What breaks if I change X?\" | `.claude\u002Fskills\u002Fgitnexus\u002Fgitnexus-impact-analysis\u002FSKILL.md` |\n| Trace bugs \u002F \"Why is X failing?\" | `.claude\u002Fskills\u002Fgitnexus\u002Fgitnexus-debugging\u002FSKILL.md` |\n| Rename \u002F extract \u002F split \u002F refactor | `.claude\u002Fskills\u002Fgitnexus\u002Fgitnexus-refactoring\u002FSKILL.md` |\n| Tools, resources, schema reference | `.claude\u002Fskills\u002Fgitnexus\u002Fgitnexus-guide\u002FSKILL.md` |\n| Index, status, clean, wiki CLI commands | `.claude\u002Fskills\u002Fgitnexus\u002Fgitnexus-cli\u002FSKILL.md` |\n\n\u003C!-- gitnexus:end -->\n","# AGENTS.md\n\nGuidance for AI coding agents working on the **adeptability** (`adept`) codebase.\nHumans: see [README.md](README.md) for usage and [CONTRIBUTING.md](CONTRIBUTING.md) for the contributor workflow.\n\n## Project Overview\n\n`adept` is a single-binary Go CLI for **cross-harness AI skill portability**: you author a\nskill once in a canonical format and `adept` renders it accurately into every AI coding\nharness in your project — Claude Code, Cursor, Codex, GitHub Copilot, OpenCode, and any\nconfig-driven adapter you register — then keeps the two sides in sync in both directions.\n\n- **Language:** Go 1.25, [Cobra](https:\u002F\u002Fgithub.com\u002Fspf13\u002Fcobra) command surface.\n- **Module:** `github.com\u002Fitaywol\u002Fadeptability`. Binary: `adept` (entrypoint `cmd\u002Fadept`).\n- **No runtime services.** Everything is local filesystem + `git` + optional network\n  (GitHub API, skills.sh, an LLM provider for the optional intent pass).\n- **Source of truth is the filesystem.** Content hashes — not version numbers — drive every\n  sync decision. There is no central database.\n\n## Commands\n\nUser-facing CLI (five verbs + three subcommand groups):\n\n| Command | Description |\n| --- | --- |\n| `adept init [--from \u003Curl>] [--ref \u003Cbranch>] [--name \u003Clocal>] [--mode symlink\\|copy]` | Scaffold `.adeptability\u002F`, optionally clone a library, adopt existing harness files |\n| `adept status` | Project state at a glance: init, libraries, harnesses, drift |\n| `adept sync [--harness \u003Cid>] [--force] [--dry-run]` | Push canonical skills → every enabled harness |\n| `adept sync-from [--harness \u003Cid>] [--all] [--force] [--dry-run]` | Adopt harness-side edits back into canonical |\n| `adept diff [--harness \u003Cid>]` | Show drift between canonical and rendered output |\n| `adept harness {add\\|remove\\|list}` | Manage enabled harnesses |\n| `adept skill {add\\|install\\|update\\|info\\|search\\|check\\|edit\\|remove\\|list}` | Manage canonical skills (local + skills.sh\u002FGitHub) |\n| `adept library {add\\|remove\\|list}` | Manage remote skill-library remotes |\n| `adept config {list\\|get\\|set\\|unset\\|llm ...}` | Strict-typed project config |\n\nGlobal flags: `--json`, `--log-level debug|info|warn|error`, `--project \u003Cpath>`, `--library \u003Cpath>`.\nRun `adept \u003Ccmd> --help` for the authoritative, always-up-to-date surface.\n\n## Architecture\n\n```\ncmd\u002Fadept\u002F            main(): injects build info, calls cli.NewRoot, maps errors→exit codes\ninternal\u002Fcli\u002F         Cobra composition root. One file per command group. NO package state.\npkg\u002Fadept\u002F            STABLE public types + interfaces + sentinel errors (no behavior here)\npkg\u002Fadeptschema\u002F      embedded JSON Schemas (skill \u002F adapter \u002F org \u002F config) for validation\ninternal\u002Fcanonical\u002F   parse skill.yaml & SKILL.md frontmatter → *adept.Skill, schema-validate\ninternal\u002Frender\u002F\u003Ch>\u002F  one package per built-in harness: Renderer + Import (reverse render)\ninternal\u002Fadapter\u002F     config-driven (YAML) harness adapters: load, validate, synthesize\ninternal\u002Fharness\u002F     orchestrator: sync \u002F sync-from \u002F drift detection across all harnesses\ninternal\u002Fmerge\u002F       3-way merge + diff3 for sync-from conflict handling\ninternal\u002Flibrary\u002F     centralized + multi-library skill resolution (first-wins on collision)\ninternal\u002Fscan\u002F        static safety scanner (+ optional LLM intent pass)\ninternal\u002Fregistry\u002F    github (trees API) + skillssh (skills.sh catalog) clients\ninternal\u002Fgit\u002F         git clone\u002Fpull\u002Fcheckout-at-SHA wrapper\ninternal\u002F{fsutil,locks,hash,config,project,log,budget,org}\u002F  supporting primitives\n```\n\n### Core invariants — do not break these\n\n1. **`pkg\u002Fadept` holds types, not behavior.** It must stay dependency-light (import-free\n   where possible — e.g. `SkillIDPattern` is a string, compiled in `internal\u002Fcanonical`).\n   In-process consumers (tests, future LSP\u002Fplugins) depend on it; keep it stable.\n2. **Composition root, no globals.** `cli.NewRoot` wires every concrete implementation\n   behind an interface into a `*Deps` container. No package-level state, no `init()` side\n   effects. Every command takes its dependencies explicitly so it can be unit-tested with\n   mocks. Add a new dependency by extending `Deps`, not by reaching for a singleton.\n3. **Identity is `(id, content-hash)`.** Skills carry no version field; the hash is the\n   answer to \"did this change\". Do not introduce version numbers as a sync signal.\n4. **Canonical layout:** a skill is a directory `\u003Croot>\u002Fskills\u002F\u003Cid>\u002F` with one `SKILL.md`\n   (YAML frontmatter + markdown body) plus optional sidecars (`scripts\u002F`, `references\u002F`,\n   `assets\u002F`). The directory name is the authoritative id. Skill ids use the\n   harness-compatible charset `^[a-z0-9](?:[a-z0-9-]{0,48}[a-z0-9])?$` (no underscore).\n   Per-skill, per-harness overrides live in an optional `harness:` map (keyed by harness id)\n   plus a promoted `model` field; renderers merge their entry last via `common.MergeOverride`,\n   and the schema forbids overriding identity fields. Currently consumed by claude-code and cursor.\n5. **Harness models differ — renderers must respect them:** per-skill (Claude, OpenCode),\n   single-file (Cursor — drops sidecars), and aggregator (Codex\u002FCopilot — concatenate into\n   one file with section markers under a byte budget). Aggregators must parse their own\n   markers on `Import` and degrade to a single synthesized skill when markers are absent.\n6. **Secrets never touch disk.** `config.json` records *which* LLM provider\u002Fmodel is used;\n   API keys are resolved from the environment (`ANTHROPIC_API_KEY`) at call time only.\n\n### Exit codes (see `cli.ExitFromError`)\n\n- `0` clean · `1` generic error · `2` dirty\u002Fdrift (`ErrDirty`) or merge conflict (`ErrMergeConflict`).\n- Safety scan worst-severity maps to the same scheme: `clean`\u002F`low`\u002F`medium` → 0, `high` → 1, `critical` → 2.\n\n## Key Integration Points\n\n- **`pkg\u002Fadept`** — `HarnessAdapter`, `Renderer`, `Skill`, `RenderOutput`, `DriftReport`,\n  `ImportedSkill`, sentinel errors (`ErrSkillNotFound`, `ErrMergeConflict`, …), on-disk\n  layout constants (`BaseDirName`, `SkillsDirName`, …). Start here to understand contracts.\n- **`pkg\u002Fadeptschema\u002F*.schema.json`** — embedded JSON Schemas. Changing a canonical field\n  means updating the schema *and* the Go struct tags in `pkg\u002Fadept` together.\n- **`internal\u002Fcli\u002Fdeps.go`** — the `Deps` wiring. New commands are constructed from `Deps`.\n- **`testdata\u002F` golden fixtures** under each `internal\u002Frender\u002F\u003Ch>\u002F` package pin exact output.\n\n## Development\n\n```bash\ngo build .\u002F...                 # build everything\ngo build -o \u002Ftmp\u002Fadept .\u002Fcmd\u002Fadept   # build the binary\ngo test .\u002F...                  # fast tests\ngo test -race .\u002F...            # race detector (CI gate)\ngo test -run E2E .\u002Fcmd\u002Fadept   # end-to-end (builds the binary, drives real commands)\ngo vet .\u002F...\ngofmt -l .                     # must print nothing\ngolangci-lint run              # config in .golangci.yml\n```\n\n### Dogfooding\n\nThis repo is itself an adept skill library — committed skills live in `skills\u002F`, and the\nproject-canonical layout (`.adeptability\u002F`, `.claude\u002F`) is **regenerated on demand and\ngitignored**. To regenerate and verify rendering locally:\n\n```bash\nadept init --from \"$(git rev-parse --show-toplevel)\" --name adept --mode copy\nadept harness add claude-code\nadept sync\nadept status\n```\n\n## Code Style\n\n- **Formatting:** `gofmt` + `goimports`. CI fails on any unformatted file — run `gofmt -w .`\n  before committing. There is no separate formatter to learn.\n- **Linting:** `.golangci.yml` enables `errcheck`, `staticcheck`, `govet`, `gocritic`,\n  `revive` (exported symbols need doc comments), `errorlint`, `nilerr`, `bodyclose`,\n  `prealloc`, `unconvert`, `misspell`, and more. Run `golangci-lint run` locally.\n- **Errors:** wrap with context — `fmt.Errorf(\"doing X: %w\", err)`. Compare with\n  `errors.Is` against the sentinels in `pkg\u002Fadept\u002Ferrors.go`; add a new sentinel there\n  rather than matching on error strings. Never silently drop an error that loses data.\n- **Naming & shape:** small, single-responsibility functions; prefer early returns over\n  deep nesting; doc comments on every exported symbol (full sentences, starting with the\n  symbol name).\n- **Commits:** [Conventional Commits](https:\u002F\u002Fwww.conventionalcommits.org\u002F). Release-please\n  derives the next semver from the types (`feat` → minor, `fix`\u002F`perf` → patch,\n  `feat!`\u002F`BREAKING CHANGE:` → major; `refactor`\u002F`docs`\u002F`chore`\u002F`test`\u002F`ci` → no bump).\n\n## Testing\n\n- **Table-driven tests** are the default. Use `testify\u002Frequire` for assertions.\n- **Golden fixtures** live in `testdata\u002F` beside each renderer; they pin exact rendered\n  bytes. When you intentionally change output, update the fixture in the same commit and\n  explain why in the message.\n- **E2E** (`cmd\u002Fadept\u002F*_test.go`) builds the real binary and drives commands against temp\n  dirs with an isolated `HOME` and `ADEPT_LIBRARY`. Guard slow paths with\n  `if testing.Short()`.\n- **Coverage gates:** keep `internal\u002Frender`, `internal\u002Fstatus`, `internal\u002Fbudget`, and\n  `internal\u002Fcanonical` at ≥80%. Tests should catch regressions, not pad coverage.\n\n## Adding a harness\n\n**Built-in (Go) adapter** — for harnesses needing custom logic:\n\n1. Implement `adept.HarnessAdapter` in `internal\u002Frender\u002F\u003Cid>\u002F`.\n2. Add golden fixtures under that package's `testdata\u002F`.\n3. Register it in `internal\u002Fcli\u002Fdeps.go` (`registerBuiltinAdapters`).\n4. Document it in the README harness table.\n\n**Config-driven adapter** — for harnesses expressible declaratively (no code, no rebuild):\n\nDrop a `\u003Cid>.yaml` adapter in `~\u002F.adeptability\u002Fadapters\u002F` matching\n`pkg\u002Fadeptschema\u002Fadapter.schema.json` (`kind` = `per-skill` | `aggregator-single` |\n`aggregator-per-glob`, plus `output`, `frontmatter`, `body`, `detect`, `import` hints).\n\n## Publishing\n\n- **Versioning:** `release-please` opens\u002Fmaintains a release PR from Conventional Commits;\n  merging it tags `vX.Y.Z`.\n- **Release:** the tag triggers `goreleaser` (cross-compiled archives for darwin\u002Flinux\u002Fwindows\n  × amd64\u002Farm64), `checksums.txt`, cosign signing, and build-provenance attestation via\n  `actions\u002Fattest-build-provenance` (immutable-release safe). Docker publish to GHCR is opt-in\n  via the `DOCKER_PUBLISH` repo variable.\n- **Distribution (live):** GitHub release tarballs, `go install`, the `scripts\u002Finstall.sh`\n  curl installer, Homebrew tap (`itaywol\u002Fhomebrew-tap`), and GHCR images.\n- **Distribution (not wired yet):** Scoop, WinGet, and the npm wrapper (`scripts\u002Fnpm\u002F`,\n  `@itaywol\u002Fadeptability`) are unpublished — tracked in the \"additional package managers\"\n  issue, gated on a thumbs-up before we commit to maintaining them.\n- Do not hand-edit `CHANGELOG.md`, `.release-please-manifest.json`, or version strings;\n  release-please owns them.\n\n\u003C!-- gitnexus:start -->\n# GitNexus — Code Intelligence\n\nThis project is indexed by GitNexus as **adeptability** (3310 symbols, 11238 relationships, 248 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.\n\n> Index stale? Run `node .gitnexus\u002Frun.cjs analyze` from the project root — it auto-selects an available runner. No `.gitnexus\u002Frun.cjs` yet? `npx gitnexus analyze` (npm 11 crash → `npm i -g gitnexus`; #1939).\n\n## Always Do\n\n- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `impact({target: \"symbolName\", direction: \"upstream\"})` and report the blast radius (direct callers, affected processes, risk level) to the user.\n- **MUST run `detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: `detect_changes({scope: \"compare\", base_ref: \"main\"})`.\n- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.\n- When exploring unfamiliar code, use `query({query: \"concept\"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.\n- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `context({name: \"symbolName\"})`.\n\n## Never Do\n\n- NEVER edit a function, class, or method without first running `impact` on it.\n- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.\n- NEVER rename symbols with find-and-replace — use `rename` which understands the call graph.\n- NEVER commit changes without running `detect_changes()` to check affected scope.\n\n## Resources\n\n| Resource | Use for |\n|----------|---------|\n| `gitnexus:\u002F\u002Frepo\u002Fadeptability\u002Fcontext` | Codebase overview, check index freshness |\n| `gitnexus:\u002F\u002Frepo\u002Fadeptability\u002Fclusters` | All functional areas |\n| `gitnexus:\u002F\u002Frepo\u002Fadeptability\u002Fprocesses` | All execution flows |\n| `gitnexus:\u002F\u002Frepo\u002Fadeptability\u002Fprocess\u002F{name}` | Step-by-step execution trace |\n\n## CLI\n\n| Task | Read this skill file |\n|------|---------------------|\n| Understand architecture \u002F \"How does X work?\" | `.claude\u002Fskills\u002Fgitnexus\u002Fgitnexus-exploring\u002FSKILL.md` |\n| Blast radius \u002F \"What breaks if I change X?\" | `.claude\u002Fskills\u002Fgitnexus\u002Fgitnexus-impact-analysis\u002FSKILL.md` |\n| Trace bugs \u002F \"Why is X failing?\" | `.claude\u002Fskills\u002Fgitnexus\u002Fgitnexus-debugging\u002FSKILL.md` |\n| Rename \u002F extract \u002F split \u002F refactor | `.claude\u002Fskills\u002Fgitnexus\u002Fgitnexus-refactoring\u002FSKILL.md` |\n| Tools, resources, schema reference | `.claude\u002Fskills\u002Fgitnexus\u002Fgitnexus-guide\u002FSKILL.md` |\n| Index, status, clean, wiki CLI commands | `.claude\u002Fskills\u002Fgitnexus\u002Fgitnexus-cli\u002FSKILL.md` |\n\n\u003C!-- gitnexus:end -->\n",{"name":5,"description":7},"main","c5b1b81b2e0ae71bd8afeeade28eaea6f8fd1bf5",".adeptability\u002Fstaging\u002F.claude\u002Fskills\u002Fagents",0,"https:\u002F\u002Fgithub.com\u002Fitaywol\u002Fadeptability","https:\u002F\u002Fpkg.go.dev\u002Fgithub.com\u002Fitaywol\u002Fadeptability","https:\u002F\u002Fgithub.com\u002Fitaywol","https:\u002F\u002Fitaywol.com","Founding Engineer @ Echo","2026-07-25 15:28:37",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add itaywol\u002Fadeptability --skill agents",{"tool":40,"command":41},"bunx","bunx skills add itaywol\u002Fadeptability --skill agents",{"tool":43,"command":44},"pnpm","pnpm dlx skills add itaywol\u002Fadeptability --skill agents","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fitaywol\u002Fadeptability\u002Fblob\u002Fmain\u002F.adeptability\u002Fstaging\u002F.claude\u002Fskills\u002Fagents\u002FSKILL.md",true,[],[49,55,60,66,72,78],{"skillNo":50,"name":51,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M756YHZ76TMVP0KK718K6KN0","using-adept","https:\u002F\u002Fgithub.com\u002Fitaywol\u002Fadeptability\u002Fblob\u002Fmain\u002Fskills\u002Fusing-adept\u002FSKILL.md",[],[],{"skillNo":56,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M756YG9YGBG4783SFH8RE5PM","https:\u002F\u002Fgithub.com\u002Fitaywol\u002Fadeptability\u002Fblob\u002Fmain\u002Fskills\u002Fagents\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M756YD5MDX9ANB4QPVN34YQX","adept-writing-tests","https:\u002F\u002Fgithub.com\u002Fitaywol\u002Fadeptability\u002Fblob\u002Fmain\u002Fskills\u002Fadept-writing-tests\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":19},"01M756YB57DN31BKNT4GHM9N2S","adept-contributing","https:\u002F\u002Fgithub.com\u002Fitaywol\u002Fadeptability\u002Fblob\u002Fmain\u002Fskills\u002Fadept-contributing\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M756Y9VM8W6E2HWMVYH0PH6H","adept-code-style","https:\u002F\u002Fgithub.com\u002Fitaywol\u002Fadeptability\u002Fblob\u002Fmain\u002Fskills\u002Fadept-code-style\u002FSKILL.md",[],[],{"skillNo":79,"name":51,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M756Y76FNSH8VWP77TX1A8Z1","Use the `adept` CLI to author an AI skill once and render it into Claude Code, Cursor, Codex, Copilot, OpenCode, and 45+ agents. Apply when installing\u002Fsyncing skills, editing SKILL.md, or touching .adeptability\u002F.","https:\u002F\u002Fgithub.com\u002Fitaywol\u002Fadeptability\u002Fblob\u002Fmain\u002Finternal\u002Fdefaultskills\u002Fassets\u002Fusing-adept\u002FSKILL.md",[],[]]