{"_id":"@acidicsoil/serena-skills-bridge","name":"@acidicsoil/serena-skills-bridge","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@acidicsoil/serena-skills-bridge","version":"0.1.0","type":"module","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"scripts":{"build":"node --experimental-strip-types scripts/build.ts","test":"npm run test:source","test:source":"node --experimental-strip-types --test test/*.test.ts","test:compiled":"node --experimental-strip-types scripts/test-compiled-cli.ts","verify":"npm run test:source && npm run build && npm run test:compiled && npm pack --dry-run --ignore-scripts","skills:inspect":"node --experimental-strip-types bin/serena-skills.ts inspect","skills:list":"node --experimental-strip-types bin/serena-skills.ts list --root matt-pocock-skills","skills:validate":"node --experimental-strip-types bin/serena-skills.ts validate --root matt-pocock-skills","prepack":"npm run build && npm run test:source && npm run test:compiled"},"description":"A Serena-native bridge for the matt-pocock-skills collection.","dependencies":{"@clack/prompts":"1.7.0","yaml":"2.9.0"},"bin":{"serena-skills":"dist/bin/serena-skills.js"},"engines":{"node":">=22.13.0"},"gitHead":"c1177c47ef45bf4b29ff41c0adacf995994e4783","_id":"@acidicsoil/serena-skills-bridge@0.1.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-WcuiES/8Yy2AitHPFs/NjZKoThJQWsKkRT8LT7R7NJBUfiGGb62W71hOzTdEGkZ8ZuqoEJ3Y0rhNShuEMMrqUg==","shasum":"e5686d0c8eff6895d67bde95b470de5991bdeaa5","tarball":"https://registry.npmjs.org/@acidicsoil/serena-skills-bridge/-/serena-skills-bridge-0.1.0.tgz","fileCount":95,"unpackedSize":344539,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAW/IBACuiB8fe57hau3ddxgvHhHcLt+ljjUyF7sbZPHAiBrEXlVNI6X6JNJG9QWWF4IOiEzVELahCh46oRl3JDbqQ=="}]},"_npmUser":{"name":"dirty-data","email":"claytonbivens1@gmail.com"},"directories":{},"maintainers":[{"name":"dirty-data","email":"claytonbivens1@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/serena-skills-bridge_0.1.0_1785965020834_0.5401525275845669"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-05T21:23:40.692Z","0.1.0":"2026-08-05T21:23:40.994Z","modified":"2026-08-05T21:23:41.248Z"},"maintainers":[{"name":"dirty-data","email":"claytonbivens1@gmail.com"}],"description":"A Serena-native bridge for the matt-pocock-skills collection.","readme":"# Serena Matt Pocock Skills Bridge\n\nA Serena-native adapter and installer for the bundled `matt-pocock-skills` collection.\n\nThe upstream `SKILL.md` files remain authoritative. The bridge discovers them recursively, preserves metadata and support files, respects model-vs-user invocation semantics, and hands the exact selected instructions to Serena. It never translates arbitrary skill prose into a second operation language.\n\n## Install\n\n```bash\nnpm install -g serena-matt-pocock-skills-bridge\nserena-skills init\n```\n\n`init` is a Clack-guided workflow in a terminal. It detects the target project and bundled skill collection, displays the full operation plan, and asks before applying it.\n\nFor automation, Serena, and CI:\n\n```bash\nserena-skills init --target . --yes --json\nserena-skills update --target . --yes --json\nserena-skills doctor --target . --json\n```\n\n## Serena integration contract\n\nSerena uses the `serena-skills` CLI as its native skills tool. It should not implement a second skill loader.\n\nA normal request flow is:\n\n```bash\nserena-skills match --request \"<user request>\" --json\nserena-skills plan --skill \"<selected name>\" --args \"<arguments>\" --json\nserena-skills invoke --skill \"<selected name>\" --args \"<arguments>\" --json\n```\n\nEvery command using `--json` writes one versioned envelope to stdout:\n\n```json\n{\n  \"schemaVersion\": \"1\",\n  \"command\": \"invoke\",\n  \"status\": \"ok\",\n  \"data\": {\n    \"status\": \"ready_for_serena\",\n    \"invocation\": {\n      \"skill\": {},\n      \"args\": null,\n      \"rawInstructions\": \"...\",\n      \"instructions\": \"...\",\n      \"supportFiles\": [],\n      \"contextDigest\": \"...\"\n    }\n  },\n  \"error\": null,\n  \"meta\": {\n    \"packageVersion\": \"0.1.0\"\n  }\n}\n```\n\nMachine callers must check `schemaVersion` and top-level `status` before consuming `data`. A successful `invoke` returns the exact rendered instructions under `data.invocation.instructions` and the upstream body under `data.invocation.rawInstructions` for traceability.\n\n### Exit codes\n\n| Code | Meaning |\n|---:|---|\n| `0` | command succeeded |\n| `1` | valid request was rejected, blocked, unhealthy, or unmatched |\n| `2` | command or option usage error |\n| `3` | malformed or invalid input data |\n| `4` | unexpected internal failure |\n\nWith `--json`, usage and runtime errors use the same envelope and write the structured error to stdout. Human-oriented errors continue to use stderr.\n\n## What `init` creates\n\n```text\n.serena-matt-pocock-skills/\n├── manifest.json\n├── modes/\n│   └── matt-pocock-skills.yml\n└── pointers.json\n\n.serena/\n├── project.yml\n└── memories/\n    └── project/\n        └── matt-pocock-skills-bridge.md\n```\n\nThe installed Serena mode and memory instruct Serena to use the CLI protocol for discovery, selection, planning, and invocation. The installer structurally patches `.serena/project.yml` to activate the bridge mode and initial prompt. It records hashes and ownership in the manifest. `update` refreshes unchanged bridge-owned artifacts, preserves the rest of the project, and blocks locally modified bridge-owned files unless `--force` is explicit.\n\n## Lifecycle commands\n\n```bash\nserena-skills init\nserena-skills update\nserena-skills doctor\n```\n\nUseful options:\n\n```text\n--target <dir>   target Serena project\n--root <dir>     override the bundled Matt Pocock skills source\n--dry-run        print the plan without writing\n--yes            apply without confirmation\n--force          replace conflicted bridge-owned artifacts\n--json           versioned machine output and no prompts\n```\n\nIn a non-TTY environment, lifecycle commands automatically avoid interactive prompts.\n\n## Skill commands\n\n```bash\nserena-skills list\nserena-skills validate\nserena-skills inspect matt-pocock-skills/engineering/tdd\nserena-skills match --request \"help me use tdd for this feature\"\nserena-skills plan --skill setup-matt-pocock-skills --args \"project-root\"\nserena-skills invoke --skill setup-matt-pocock-skills --args \"project-root\"\n```\n\n`disable-model-invocation: true` excludes a skill from automatic matching but does not prevent explicit invocation. `user-invocable: false` prevents direct user selection. `argument-hint`, named/indexed argument placeholders, `when_to_use`, and extension metadata are preserved. Rendered invocation instructions include the selected skill's base directory while retaining exact upstream Markdown separately as `rawInstructions`.\n\n## Compatibility contract\n\n- Recursive `<category>/<skill>/SKILL.md` discovery\n- Full YAML frontmatter parsing\n- Required `name` and `description`\n- Native model/user invocation and argument handling\n- Unified, cached skill registry with explicit invalidation\n- Root-bounded sibling assets and symlink checks\n- Exact upstream Markdown retained alongside rendered invocation instructions\n- No inferred shell or file operations from prose\n- Project-local Serena memory and mode activation\n- Manifest-driven, ownership-aware, idempotent updates\n- Versioned JSON CLI protocol for Serena and other machine callers\n- Stable exit-code classification\n\n## Automated verification\n\nThe repository contains one verification command that performs all required checks without a manual project walkthrough:\n\n```bash\nnpm run verify\n```\n\nIt runs:\n\n1. the complete TypeScript source test suite;\n2. the package build;\n3. an end-to-end test against `dist/bin/serena-skills.js`;\n4. a package-content dry run.\n\nThe compiled CLI test creates a temporary Serena project and automatically verifies bundled skill discovery, explicit selection, plan digests, invocation handoff, installation, `doctor`, rejection behavior, and usage exit codes. The temporary project is deleted after the run.\n\nGitHub Actions runs `npm run verify` on pushes and pull requests.\n\n## Development\n\nAll first-party bridge runtime, build, and test code under `bin/`, `scripts/`, `src/`, and `test/` is TypeScript. Node's built-in type stripping runs source files during development; `npm run build` emits package-safe JavaScript into `dist/`, including the bundled skill corpus.\n\n```bash\nnpm test\nnpm run build\nnpm run test:compiled\nnpm run verify\n```\n\nThe package entry point is `dist/bin/serena-skills.js`; published installs never execute TypeScript from `node_modules`. A source guard test rejects `.js`, `.mjs`, and `.cjs` files or relative JavaScript import specifiers in the first-party directories.\n\nVendored and upstream assets outside those directories retain their native formats and are not part of the bridge TypeScript migration.\n\nThe test suite includes unit, lifecycle, CLI, ownership-conflict, recursive collection, clean-install, registry, argument rendering, invocation-traceability, source-language, machine-protocol, and compiled-package checks.\n","readmeFilename":"README.md","_rev":"1-baa02dead3812322836755df066700c2"}