{"_id":"@3metajun/mstack","_rev":"4-78cb33365ea54b92b79ae855e5e5cbbb","name":"@3metajun/mstack","dist-tags":{"latest":"0.4.1"},"versions":{"0.2.0":{"name":"@3metajun/mstack","version":"0.2.0","license":"MIT","_id":"@3metajun/mstack@0.2.0","maintainers":[{"name":"3metajun","email":"3metajun@gmail.com"}],"homepage":"https://github.com/3metaJun/mstack#readme","bugs":{"url":"https://github.com/3metaJun/mstack/issues"},"bin":{"mstack":"scripts/install.mjs"},"dist":{"shasum":"99c3a322e82eb8ab45c79457831b63c4d42fa6d9","tarball":"https://registry.npmjs.org/@3metajun/mstack/-/mstack-0.2.0.tgz","fileCount":205,"integrity":"sha512-04Tr1IP8xEGS/AcZ8AE+nvjZqBRGTiDHWPHmku3+EU7C7zzRkTmRFmVFTp8Y6odVspWs1r36CJV45AfCLpCvig==","signatures":[{"sig":"MEQCIE4RyebWn5E4XbOxUBd7n+L3CfCN5eRoVtsFPX8vSOJZAiAiw9J1SpMhRrfvdRq3by1Jsr03pVm2h9xVzMvoHcjlag==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3328351},"type":"module","engines":{"node":">=18"},"gitHead":"aa824daa56e575643473f438d69d2662d0eeb1c4","scripts":{"test":"node scripts/validate.mjs && node --test scripts/install.test.mjs scripts/context.test.mjs scripts/audit-context.test.mjs scripts/worktree-audit.test.mjs scripts/sync-upstream.test.mjs scripts/runtime.test.mjs scripts/environment.test.mjs","run-role":"node scripts/run-role.mjs","check-models":"node scripts/model-config.mjs","audit-context":"node scripts/audit-context.mjs","check-package":"node scripts/check-package.mjs","sync-upstream":"node scripts/sync-upstream.mjs","check-upstream":"node scripts/check-upstream.mjs","install-skills":"node scripts/install.mjs","remote-install":"node scripts/remote-install.mjs","smoke-harnesses":"node scripts/smoke-harnesses.mjs","optimize-context":"node scripts/optimize-context.mjs","reconcile-context":"node scripts/reconcile-context.mjs"},"_npmUser":{"name":"3metajun","email":"3metajun@gmail.com"},"repository":{"url":"git+https://github.com/3metaJun/mstack.git","type":"git"},"_npmVersion":"11.12.1","description":"Portable engineering skills for Codex, Claude Code, OpenCode, and pi.","directories":{},"_nodeVersion":"24.15.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mstack_0.2.0_1789067729327_0.16752972101219976","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@3metajun/mstack","version":"0.3.0","license":"MIT","_id":"@3metajun/mstack@0.3.0","maintainers":[{"name":"3metajun","email":"3metajun@gmail.com"}],"homepage":"https://github.com/3metaJun/mstack#readme","bugs":{"url":"https://github.com/3metaJun/mstack/issues"},"bin":{"mstack":"scripts/install.mjs"},"dist":{"shasum":"9662dda77a3272f6f3bb2a6228f1538ba1ca2e60","tarball":"https://registry.npmjs.org/@3metajun/mstack/-/mstack-0.3.0.tgz","fileCount":226,"integrity":"sha512-GRNtrrIAwv3uo5MwwuENKF/YeWMzyIJ2nBfjVlkTDU9iiNev4Y8pEtTvCzLcprkp6k1treEBKIWPF3KKl/HV1w==","signatures":[{"sig":"MEUCIQDHfSA1rsYcUBYG+dhFCeuwr2jT6iAd3ZkedN7DW1pJ1QIgE0T0TLgAYUfTCfG+PZILzck6h64FXTGpWKJfKrtjY/M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQC8eyJZttu4y933cWMu6+I1Qy5vWuJf6x7z3Lb869w2WgIgTlTAXRiD1DAYxqLk/V5B6H8NTrtT0NIA4q3T/5Dc4Jg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3587387},"type":"module","_from":"file:G:/agents_temp/mstack-release-030-20260911/verified/3metajun-mstack-0.3.0.tgz","engines":{"node":">=18"},"scripts":{"test":"node scripts/validate.mjs && node scripts/skill-baseline.mjs --check && node --test scripts/install.test.mjs scripts/context.test.mjs scripts/model-config.test.mjs scripts/audit-context.test.mjs scripts/worktree-audit.test.mjs scripts/sync-upstream.test.mjs scripts/runtime.test.mjs scripts/environment.test.mjs scripts/skill-integrity.test.mjs scripts/skill-baseline.test.mjs scripts/version-integrity.test.mjs scripts/agent-format.test.mjs scripts/history.test.mjs","run-role":"node scripts/run-role.mjs","check-models":"node scripts/model-config.mjs","audit-context":"node scripts/audit-context.mjs","check-package":"node scripts/check-package.mjs","sync-upstream":"node scripts/sync-upstream.mjs","check-upstream":"node scripts/check-upstream.mjs","install-skills":"node scripts/install.mjs","remote-install":"node scripts/remote-install.mjs","skill-baseline":"node scripts/skill-baseline.mjs","smoke-harnesses":"node scripts/smoke-harnesses.mjs","optimize-context":"node scripts/optimize-context.mjs","reconcile-context":"node scripts/reconcile-context.mjs"},"_npmUser":{"name":"3metajun","email":"3metajun@gmail.com"},"_resolved":"G:\\agents_temp\\mstack-release-030-20260911\\verified\\3metajun-mstack-0.3.0.tgz","_integrity":"sha512-GRNtrrIAwv3uo5MwwuENKF/YeWMzyIJ2nBfjVlkTDU9iiNev4Y8pEtTvCzLcprkp6k1treEBKIWPF3KKl/HV1w==","repository":{"url":"git+https://github.com/3metaJun/mstack.git","type":"git"},"_npmVersion":"11.12.1","description":"Portable engineering skills for Codex, Claude Code, OpenCode, and pi.","directories":{},"_nodeVersion":"24.15.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mstack_0.3.0_1789126996752_0.9648117077948621","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@3metajun/mstack","version":"0.4.0","license":"MIT","_id":"@3metajun/mstack@0.4.0","maintainers":[{"name":"3metajun","email":"3metajun@gmail.com"}],"homepage":"https://github.com/3metaJun/mstack#readme","bugs":{"url":"https://github.com/3metaJun/mstack/issues"},"bin":{"mstack":"scripts/install.mjs","mstack-policy":"scripts/check-harness-policy.mjs"},"dist":{"shasum":"cd488a6d6889ba85a1873dcbc56b18815f6a00d6","tarball":"https://registry.npmjs.org/@3metajun/mstack/-/mstack-0.4.0.tgz","fileCount":235,"integrity":"sha512-5hq/3fcf0et4dGTT016NRxsdMJK4kI+FD/Pbjex/0n2FEBC7cNsnGH4AaeoVPVT7VWyZdLgnSoEGuPrhwY+brQ==","signatures":[{"sig":"MEYCIQCfu77//Xl9BhdGlsy+I3bu4xe/VSjqpuRX7baznuH9KQIhAKXP1jB8GxcVlDRFrcRAwk+ke10Z+2jzSW3wR6rgI5VW","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIH6ti0VIH6bSfBf7uah2D1LuA7CS63NReKXim+T1wjceAiAR3H5/EMZUfa5yUEFzBlnsYDS+3d6tDiAApn4Jx2o37Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3713781},"type":"module","_from":"file:G:/agents_temp/mstack-release-040/3metajun-mstack-0.4.0.tgz","engines":{"node":">=18"},"scripts":{"test":"node scripts/validate.mjs && node scripts/skill-baseline.mjs --check && node --test scripts/install.test.mjs scripts/context.test.mjs scripts/model-config.test.mjs scripts/audit-context.test.mjs scripts/worktree-audit.test.mjs scripts/sync-upstream.test.mjs scripts/runtime.test.mjs scripts/environment.test.mjs scripts/skill-integrity.test.mjs scripts/skill-baseline.test.mjs scripts/version-integrity.test.mjs scripts/agent-format.test.mjs scripts/history.test.mjs scripts/harness-policy.test.mjs scripts/harness-project.test.mjs scripts/check-upstream-adaptations.test.mjs","run-role":"node scripts/run-role.mjs","check-models":"node scripts/model-config.mjs","audit-context":"node scripts/audit-context.mjs","check-package":"node scripts/check-package.mjs","sync-upstream":"node scripts/sync-upstream.mjs","check-upstream":"node scripts/check-upstream.mjs","install-skills":"node scripts/install.mjs","remote-install":"node scripts/remote-install.mjs","skill-baseline":"node scripts/skill-baseline.mjs","smoke-harnesses":"node scripts/smoke-harnesses.mjs","optimize-context":"node scripts/optimize-context.mjs","reconcile-context":"node scripts/reconcile-context.mjs","check-harness-policy":"node scripts/check-harness-policy.mjs"},"_npmUser":{"name":"3metajun","email":"3metajun@gmail.com"},"_resolved":"G:\\agents_temp\\mstack-release-040\\3metajun-mstack-0.4.0.tgz","_integrity":"sha512-5hq/3fcf0et4dGTT016NRxsdMJK4kI+FD/Pbjex/0n2FEBC7cNsnGH4AaeoVPVT7VWyZdLgnSoEGuPrhwY+brQ==","repository":{"url":"git+https://github.com/3metaJun/mstack.git","type":"git"},"_npmVersion":"11.12.1","description":"Portable engineering skills for Codex, Claude Code, OpenCode, and pi.","directories":{},"_nodeVersion":"24.15.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mstack_0.4.0_1789189990885_0.35648161875759543","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"_id":"@3metajun/mstack@0.4.1","bin":{"mstack":"scripts/install.mjs","mstack-policy":"scripts/check-harness-policy.mjs"},"bugs":{"url":"https://github.com/3metaJun/mstack/issues"},"dist":{"shasum":"5910aac79072080682b1416390752fd533f8245a","tarball":"https://registry.npmjs.org/@3metajun/mstack/-/mstack-0.4.1.tgz","fileCount":243,"integrity":"sha512-kN7kcOSA8l4EEmty7zkL15V0nN6f8xATH7OGKtH6idXMRQ+lbH/SUF4lkiyjIz+pcEO8Ae0BJpawDxF9R6PU5w==","signatures":[{"sig":"MEUCIQC+ArAPXB3reCVWSziy4PYcCfjCPg5F3Er4tOlg8XRZygIgGWkIo7R5VBxFzm6XGhCz6iiLNL95ljvB8QZqXUqWpok=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDHL7b//toCnvf+LeeXyswJH8GxrbuEgU5DWnaS0foF+AiEAqZAqBRbIwwnbqO29yMAQj6xOOijky/cFYeYk+vFL/o0="}],"unpackedSize":3776290},"name":"@3metajun/mstack","type":"module","_from":"file:G:/agents_temp/mstack-release-0.4.1/3metajun-mstack-0.4.1.tgz","engines":{"node":">=18"},"license":"MIT","scripts":{"test":"node scripts/validate.mjs && node scripts/skill-baseline.mjs --check && node --test scripts/install.test.mjs scripts/install-migration.test.mjs scripts/migration-integration.test.mjs scripts/skill-discovery.test.mjs scripts/harness-targets.test.mjs scripts/remote-discovery.test.mjs scripts/context.test.mjs scripts/model-config.test.mjs scripts/audit-context.test.mjs scripts/worktree-audit.test.mjs scripts/sync-upstream.test.mjs scripts/runtime.test.mjs scripts/environment.test.mjs scripts/skill-integrity.test.mjs scripts/skill-baseline.test.mjs scripts/version-integrity.test.mjs scripts/agent-format.test.mjs scripts/history.test.mjs scripts/harness-policy.test.mjs scripts/harness-project.test.mjs scripts/check-upstream-adaptations.test.mjs","run-role":"node scripts/run-role.mjs","check-models":"node scripts/model-config.mjs","audit-context":"node scripts/audit-context.mjs","check-package":"node scripts/check-package.mjs","sync-upstream":"node scripts/sync-upstream.mjs","check-upstream":"node scripts/check-upstream.mjs","install-skills":"node scripts/install.mjs","remote-install":"node scripts/remote-install.mjs","skill-baseline":"node scripts/skill-baseline.mjs","smoke-harnesses":"node scripts/smoke-harnesses.mjs","optimize-context":"node scripts/optimize-context.mjs","reconcile-context":"node scripts/reconcile-context.mjs","check-harness-policy":"node scripts/check-harness-policy.mjs"},"version":"0.4.1","_npmUser":{"name":"3metajun","email":"3metajun@gmail.com"},"homepage":"https://github.com/3metaJun/mstack#readme","_resolved":"G:\\agents_temp\\mstack-release-0.4.1\\3metajun-mstack-0.4.1.tgz","_integrity":"sha512-kN7kcOSA8l4EEmty7zkL15V0nN6f8xATH7OGKtH6idXMRQ+lbH/SUF4lkiyjIz+pcEO8Ae0BJpawDxF9R6PU5w==","repository":{"url":"git+https://github.com/3metaJun/mstack.git","type":"git"},"_npmVersion":"11.12.1","description":"Portable engineering skills for Codex, Claude Code, OpenCode, and pi.","directories":{},"maintainers":[{"name":"3metajun","email":"3metajun@gmail.com"}],"_nodeVersion":"24.15.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mstack_0.4.1_1789198927815_0.42595435284186833"}}},"time":{"created":"2026-09-10T19:15:29.120Z","modified":"2026-09-12T07:42:08.189Z","0.2.0":"2026-09-10T19:15:29.769Z","0.3.0":"2026-09-11T11:43:16.919Z","0.4.0":"2026-09-12T05:13:11.092Z","0.4.1":"2026-09-12T07:42:08.031Z"},"bugs":{"url":"https://github.com/3metaJun/mstack/issues"},"license":"MIT","homepage":"https://github.com/3metaJun/mstack#readme","repository":{"url":"git+https://github.com/3metaJun/mstack.git","type":"git"},"description":"Portable engineering skills for Codex, Claude Code, OpenCode, and pi.","maintainers":[{"name":"3metajun","email":"3metajun@gmail.com"}],"readme":"# mstack\n\n[![CI](https://github.com/3metaJun/mstack/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/3metaJun/mstack/actions/workflows/validate.yml)\n[![npm version](https://img.shields.io/npm/v/%403metajun%2Fmstack?logo=npm&logoColor=white)](https://www.npmjs.com/package/@3metajun/mstack)\n\nmstack packages portable engineering skills for Codex, Claude Code, OpenCode,\nand pi. One canonical `skills/` tree feeds every supported harness. The\ninstaller adapts harness metadata at install time, so skill instructions do not\ncontain harness-specific paths or commands.\n\n![mstack portable engineering skills across Codex, Claude Code, OpenCode, and pi](https://raw.githubusercontent.com/3metaJun/mstack/main/.github/assets/social-preview.png)\n\nThe collection started with selected workflows from\n[`pstack`](https://github.com/cursor/plugins/tree/main/pstack/skills) and\n[`mattpocock/skills`](https://github.com/mattpocock/skills). Source and license\nrecords live in [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md).\n\n## Install skills\n\nNode.js 18 or newer is required.\n\nTo install every skill for every supported harness, run:\n\n```bash\nnpx @3metajun/mstack --harness all\n```\n\nTo install skills for selected harnesses, list them with commas:\n\n```bash\nnpx @3metajun/mstack --harness codex,claude\nnpx @3metajun/mstack --harness opencode,pi\n```\n\nTo install selected skills, add `--skill`:\n\n```bash\nnpx @3metajun/mstack --harness all \\\n  --skill writing-for-agents,codebase-design,diagnosing-bugs\n```\n\nThe installer preserves an existing skill directory. Use `--dry-run` to inspect\nthe plan. Use `--replace` to move existing directories into a timestamped\n`.harness-skills-backups/` directory outside the skill root. Backups, staged\nskills and failed replacements must stay outside discovery roots because\nOpenCode also scans hidden subdirectories. Artifact backups stay beside the\nartifact target. The installer prints each backup path and retains its contents.\n\n## Install optional artifacts\n\nThe same installer can copy the portable artifacts that accompany the skills.\nBy default it installs skills only. Select artifacts explicitly, or use\n`--no-skills` when an artifact-only install is needed:\n\n```bash\nnpx @3metajun/mstack --harness codex --artifact agents,meta-mode-tools\nnpx @3metajun/mstack --harness all --no-skills --artifact all\n```\n\nThe available installable artifacts are:\n\n| Artifact | Default destination |\n| --- | --- |\n| `agents` | Codex: `$CODEX_HOME/agents/` as TOML; other harnesses: their native `agents/` directory as Markdown |\n| `meta-mode-tools` | `tools/meta-mode/` beside the resolved skill root; shared consumers use `~/.agents/tools/meta-mode/` |\n| `guide` | `docs/guide/` beside the resolved skill root |\n\nCodex skills default to `~/.agents/skills/`, while Codex agents default to\n`~/.codex/agents/`. An unset or empty `CODEX_HOME` uses `~/.codex`.\n`HARNESS_SKILLS_CODEX_DIR` relocates skills only; agents follow `CODEX_HOME`\nunless an artifact override is supplied. Codex TOML and Markdown agents must\nuse separate target directories. Shared targets are allowed only when the\nartifact source and output format match.\n\nFor SSH installs, both `/home/dev/.agents/skills` and\n`/home/dev/.codex/skills` map agents to `/home/dev/.codex/agents`.\nFor a custom remote layout or remote `CODEX_HOME`, set\n`artifacts.agents.codex` to that remote agent directory. The installer cannot\ninfer a remote home from an arbitrary skill path or the local `CODEX_HOME`.\n\nArtifact destinations can be overridden per harness with\n`MSTACK_ARTIFACT_<ARTIFACT>_<HARNESS>_DIR`, for example\n`MSTACK_ARTIFACT_AGENTS_CODEX_DIR`. Named environments can provide the same\noverrides in either shape below (artifact-first is the documented form):\n\n```json\n{\n  \"fleet\": {\n    \"targets\": {\n      \"codex\": \"C:\\\\path\\\\to\\\\Fleet\\\\codex\\\\skills\"\n    },\n    \"artifacts\": {\n      \"agents\": {\n        \"codex\": \"C:\\\\path\\\\to\\\\Fleet\\\\codex\\\\agents\"\n      }\n    }\n  }\n}\n```\n\n`benny` is intentionally listed in `profiles/artifacts.json` as a\nCursor-only source and is rejected by the cross-harness installer. It must be\nreviewed and copied into a project repository's committed\n`.cursor/automations/benny/` directory using its own setup instructions.\nmstack does not ship portable `commands/`, `hooks/`, or `settings/` trees:\nthose are harness- and project-owned configuration surfaces and must be\nwritten or merged explicitly by the user.\n\n## Choose installation directories\n\nThe default directories are defined in\n[`profiles/harnesses.json`](./profiles/harnesses.json):\n\n| Harness | Default directory | Override |\n| --- | --- | --- |\n| Codex | `~/.agents/skills/` | `HARNESS_SKILLS_CODEX_DIR` |\n| Claude Code | `~/.claude/skills/` | `HARNESS_SKILLS_CLAUDE_DIR` |\n| OpenCode | `~/.agents/skills/` | `HARNESS_SKILLS_OPENCODE_DIR` |\n| pi | `~/.agents/skills/` | `HARNESS_SKILLS_PI_DIR` |\n\nCodex, OpenCode and pi share one physical copy per skill by default. Updating\nthrough any of these Harnesses updates that shared copy. Claude gets its own\nadapter output without a frontmatter `name`: Claude uses the directory name,\nwhile OpenCode skips that copy. No global Harness settings are changed.\n\nOpenCode and pi agent artifacts retain their native configuration roots.\n`CLAUDE_CONFIG_DIR`, `XDG_CONFIG_HOME` and `PI_CODING_AGENT_DIR` still resolve\nnative roots and legacy migration locations; the latter two no longer move\nthe default shared skills. Use `HARNESS_SKILLS_*_DIR` for explicit skill paths.\n\nSet an override to install into a mounted Fleet directory or another local\npath. The path must be absolute or start with `~/`. Explicit overrides and\nnamed environment targets are not rewritten. Equal targets are combined only\nwhen their selected skill adapters agree; Claude and canonical output cannot\nshare a target. Keep explicit copies out of overlapping discovery paths.\n\n### Migrate an existing installation\n\nRun the new installer locally on the machine that owns the skills:\n\n```bash\nnpx @3metajun/mstack --harness all --migrate --replace --dry-run\nnpx @3metajun/mstack --harness all --migrate --replace\n```\n\nMigration moves recognized legacy OpenCode and pi copies into backups outside\nskill discovery. It also moves old installer backup trees and recognized\nstaging leftovers out of discovery.\nA partial shared update checks the same selected names in all native roots,\nincluding Harnesses not named on the command line. Existing Claude copies\nthat need only directory-based identity are adapted from their installed\ncontents, preserving supporting files and body edits. Directly selected skills\nare replaced from the package, with their original contents backed up.\n\nOwnership comes from an mstack install receipt or known released `SKILL.md`\ncontent from versions 0.2.0 through 0.4.0. An unrecognized same-name legacy copy\nstops migration before writes; inspect and relocate that copy before retrying.\nUnselected active skills and unrelated skill names remain in place. Re-running\nthe migration is safe, and a later failed write rolls back earlier migrations.\n\nWithout `--migrate`, the installer reports legacy copies that would remain\nactive. Automatic migration requires a default shared local target. For SSH or\nmounted custom layouts, run migration on the target machine with its native\npaths; SSH `--migrate` is rejected before connecting. SSH dry-run validates\nconfigured destinations but does not inspect the remote filesystem.\n\n### Custom and remote targets\n\n```powershell\n$env:HARNESS_SKILLS_OPENCODE_DIR = 'C:\\path\\to\\fleet\\opencode\\skills'\nnpx @3metajun/mstack --harness opencode\n```\n\nFor named local or mounted environments, copy\n[`profiles/environments.example.json`](./profiles/environments.example.json) to\n`~/.config/mstack/environments.json`, replace the paths, and pass the name:\n\n```bash\nnpx @3metajun/mstack --harness opencode --environment fleet\n```\n\nSet `MSTACK_ENVIRONMENTS_FILE` to use another environment file. Each target must\nbe an absolute path or start with `~/` for local environments.\n\nFor a Tailscale, VPS, or Mac mini target, use an SSH environment. The machine\nrunning mstack must have Node.js, `ssh`, and `rsync`. The target must expose a\nPOSIX shell and `rsync`; it needs the selected Harness CLI only when roles or\nlive smoke tests will run there:\n\n```json\n{\n  \"fleet-ssh\": {\n    \"transport\": \"ssh\",\n    \"host\": \"dev@tailnet-host\",\n    \"shell\": \"posix\",\n    \"targets\": {\n      \"opencode\": \"/home/dev/.config/opencode/skills\"\n    }\n  }\n}\n```\n\nPut identity and connection options in the SSH host alias when possible. If an\nenvironment supplies them directly, configure both transports because `rsync`\nstarts its own SSH process and does not reuse `sshArgs`:\n\n```json\n{\n  \"sshArgs\": [\"-i\", \"/home/dev/.ssh/id_ecdsa.pem\"],\n  \"rsyncArgs\": [\"-e\", \"ssh -i /home/dev/.ssh/id_ecdsa.pem\"]\n}\n```\n\nThe same `npx @3metajun/mstack --harness opencode --environment fleet-ssh`\ncommand stages\nlocally, transfers with `rsync`, takes a remote lock, and moves each selected\ndirectory into place. Add `--dry-run` to print the remote plan without opening\nan SSH connection. Windows remotes can still be used through a mounted path;\nremote installation currently targets POSIX shells.\n\nRemote lock directories record a timestamped owner. After an interrupted\ninstall, inspect `<target-parent>/.mstack.install.lock/owner`, verify that no\ninstall is running, remove the lock directory, and retry.\n\nThe SSH/rsync path has been verified end to end against a disposable POSIX\ntarget, including remote locking, atomic installation, checksum comparison,\nand cleanup.\n\n## Run a configured role\n\n`run-role` turns a configured role into the selected Harness command. Without\n`--execute` it only prints the plan:\n\n```bash\nnpm run run-role -- --harness opencode --role explorer \\\n  --prompt \"Inspect the repository and do not edit files\" \\\n  --environment fleet-ssh --model auto\n```\n\nAdd `--execute` to run the command. SSH environments pass the prompt through\nstrict POSIX quoting or a PowerShell encoded command, depending on `shell`.\n\nModel roles live in `~/.config/mstack/models.json`. Each role accepts a model\nstring. The `reviewer` role also accepts a non-empty list of unique model strings.\nA Harness override replaces the role's whole value. Use `/setup-mstack` to choose\nnames reported by your Harness; existing string configurations remain valid.\n\n`inherit-parent` requests the current chat model. Native delegation can use its\ndocumented inheritance mechanism, but `run-role` starts a new CLI process and\nrequires `--parent-model <known-parent-model>` for that value. `auto` omits the\nmodel argument and selects the CLI's default, which may be different. Existing\nCLI calls that used `inherit-parent` must add `--parent-model`, or explicitly\nchoose `--model auto`. With no configuration file, the seven roles default to\n`inherit-parent`, so the same choice is required.\n\nFor a configured reviewer list, select one entry with `--model-index 0` or run\nall entries concurrently:\n\n```bash\nnpm run run-role -- --harness codex --role reviewer \\\n  --file ~/.config/mstack/models.json --prompt \"Review this diff\" \\\n  --all-models --read-only --execute\n```\n\nReplace `roles.reviewer` or `overrides.codex.reviewer` with a JSON array of the\nmodel names you selected. Add `--parent-model <known-parent-model>` if an entry\nis `inherit-parent`. Without `--execute`, fanout prints a JSON array of plans.\nExecution returns a JSON array with each model's `stdout`, `stderr`, and `status`,\nin configuration order. A string role used with `--all-models` returns the same\narray shape with one entry. Any failure makes the overall exit code nonzero. Output\nis buffered up to 16 MiB per stream per worker; larger output fails that worker.\n`--all-models` requires `--read-only`. Writable workers need individual launches\nwith separate worktrees. Review the Harness's read-only limits below.\n\n## Smoke test Harnesses\n\nCheck CLI availability and installed skill files after installation:\n\n```bash\nnpm run smoke-harnesses -- --harness all --require-installed\n```\n\nAdd `--execute` for a live prompt on every available Harness. It uses the CLI\ndefault model unless you supply `--model`, `--parent-model`, or a `--file` with\nmodel choices. An inherited role in that file needs `--parent-model`. The live\nprompt checks a reply marker; it does not prove that the Harness loaded the skill\nor completed its workflow. These live calls always use `--read-only`.\nCodex, Claude Code, and pi use CLI-enforced tool restrictions.\nOpenCode selects its built-in `plan` agent, which denies direct edits but still\nallows shell commands in OpenCode 1.18; use a disposable checkout when its\nprompt-only write boundary is insufficient. A live check also needs that\nHarness's credentials and configured model access.\n\nThe Claude live path was verified with Claude Code 2.1.267, the Kiro-Pro\nconfiguration, and `claude-haiku-4-5-20251001`. The check required Claude\nCode's native `Skill` tool to invoke `meta-mode` and return an exact marker;\nthe remote fixture and temporary credentials were removed afterward.\n\n## Recover recent context\n\n`recall` includes a history reader in `recall/scripts/history.mjs`; it also works\nwhen only the skill directory is installed. List session metadata for the active\nworkspace before selecting a session to read:\n\n```bash\nnode <recall-directory>/scripts/history.mjs list --harness codex --workspace <workspace> --exclude <current-session-id>\nnode <recall-directory>/scripts/history.mjs read --harness codex --workspace <workspace> --session <session-id> --query parser\n```\n\nThe reader supports Codex, Claude Code, OpenCode, and pi, with configured storage\nroots, session exclusions, branch selection where available, and bounded text\noutput. OpenCode exports are sanitized by default; explicitly use `--local-text`\nfor private local recovery because sanitization can remove all message text.\nSee [history sources](./skills/recall/references/history-sources.md) for supported\nformats and limits. Tests use disposable sessions; no user transcript is bundled.\n\nThe [authoring playbook](./skills/meta-mode/playbooks/authoring-a-skill.md) gives\n`automate-me` and `reflect` a concrete draft, description review, and validation\nworkflow even when no native skill creator or repository validator is installed.\n\n## Repository layout\n\n- `skills/` contains the canonical, harness-neutral skill files.\n- `adapters/` contains per-harness frontmatter changes.\n- `profiles/harnesses.json` defines supported harnesses and default paths.\n- `docs/harness-adapters.md` records the official skill and session rules used\n  by each Harness adapter.\n- `profiles/artifacts.json` defines optional artifacts and documents unsupported\n  harness-owned surfaces.\n- `profiles/skills.json` defines the canonical skill inventory.\n- `profiles/upstreams.json` records source commits and renamed entries.\n- `profiles/models.example.json` gives model-role configuration a portable\n  shape without forcing a provider.\n- `agents/` contains portable routing and comment-review agents.\n- `automations/benny/` keeps the optional Cursor automation pack from pstack.\n- `docs/guide/` contains the adapted upstream workflow guide.\n- `tools/meta-mode/` contains the optional Bun orchestration and PR watcher\n  tools.\n- `scripts/install.mjs` stages, validates, and commits an installation.\n- `scripts/remote-install.mjs` stages and transfers an SSH environment install.\n- `scripts/validate.mjs` checks inventory, frontmatter, links, and portability.\n- `scripts/check-harness-policy.mjs` validates a business repository's mixed\n  pstack/mstack policy and detects duplicate verification maps.\n- `.codex-plugin/` packages the same skill tree for Codex.\n\nThe installer stages every selected skill, applies its adapter, validates the\nresult, and then renames the staged directory into place. It uses a lock per\ntarget directory and restores backups if a commit fails.\n\n## Included skills\n\nThe current bundle contains 50 skills. It includes the 47 entries in the\nportable pstack tree and three skills adapted from `mattpocock/skills`:\n\n- Engineering principles for boundaries, domain modelling, idempotence,\n  verification, sequencing, and type safety.\n- Workflows for diagnosis, design review, context recovery, TDD, and agent\n  instruction writing.\n- `create-verification-skill` for generating a project-specific verification\n  workflow.\n- `meta-mode` for routing a multi-step task through the capabilities available\n  in the current harness.\n\nThe bundle includes the pstack workflow and principle names. `meta-mode` is the\nportable replacement for pstack's `poteto-mode`; it describes capabilities and\nuses the current harness's adapter instead of naming one vendor's commands.\n\nRun `node scripts/validate.mjs` to print the validated skill count.\n\nFor a business repository that mixes pstack and mstack, initialize its shared\nproject workflow with the CLI available in mstack 0.4.0 and later:\n\n```bash\nnpx --package @3metajun/mstack@0.4.0 mstack-policy init --root <project> --app web --check 'node --test' --pstack <exact-pstack-commit>\n```\n\nReplace the app, check command, and pstack revision with the project's values.\nInitialization exports `.harness/check.mjs` and its library for committed CI\nchecks that run without downloading mstack. It leaves the application\ncontract for `/create-verification-skill` to create or migrate and prove. See\n[mixed-Harness adoption](./docs/guide/11-mixed-harness.md) for wrapper generation,\nreceipts, repository protection, and reviewed checker upgrades. Pin the team's\nexact package version for initialization and run recording.\n\nTo validate and print a user's model configuration, run:\n\n```bash\nnpm run check-models -- --file ~/.config/mstack/models.json\n```\n\nTo check the complete skill trees against both pinned upstreams, run:\n\n```bash\nnpm run skill-baseline -- --check --source /path/to/pstack --matt-source /path/to/mattpocock-skills\n```\n\nThis checks every file in all 50 skill trees, including references, playbooks,\nand scripts. It also checks tools moved out of skill directories. Local\nadditions and intentional upstream omissions are recorded explicitly. Both\nsource checkouts must be clean and at their pinned commits. `npm test` checks\nthe target files without needing upstream checkouts.\n\nFor intentional changes, preview with the same source arguments and `--diff`,\nreview the source-to-adaptation patches, then use `--write` to update\n`profiles/skill-manifest.json`. Commit the baseline with the corresponding\ncontent changes. The hashes detect drift; they do not establish that an adapted\nworkflow behaves like its source. See [the baseline review process](docs/skill-integrity.md).\n\nTo compare the pstack inventory and non-skill artifacts, run:\n\n```bash\nnpm run check-upstream -- --source /path/to/pstack\n```\n\nThe check applies the renames in `profiles/upstreams.json`, verifies the\nreviewed body digest for every canonical pstack skill, reports the portable\nskill count, and reports the state of the agents, Benny automation, guide, and\nmeta-mode tools. Add `--strict` to fail when a canonical skill body or\nconfigured artifact is missing, differs, or remains after removal upstream.\nStrict mode requires the source to be a clean Git checkout whose `HEAD` exactly\nmatches the pinned commit. If you intentionally edit a canonical skill, update\nits reviewed target digest in `canonicalSkills` as part of that review; sync\npreserves these entries and does not silently re baseline them.\n\nTo preview and apply a transformed refresh of those non-skill artifacts:\n\n```bash\nnpm run sync-upstream -- --source /path/to/pstack\nnpm run sync-upstream -- --source /path/to/pstack --apply\n```\n\nThe sync command is dry-run by default. It transforms pstack and poteto names\nto mstack and meta names, preserves adapted agents, and refuses to overwrite\nchanged source-managed files. `--apply` requires the same clean, pinned source\ncheckout as strict checking. It removes files deleted upstream only when their\ncontent still matches the previous manifest. Pass `--apply --force` after\nreviewing a diff when overwriting or removing a locally changed file is\nintentional.\n\nAll sync commands use one exclusive lock per target, so concurrent `--apply`,\ndry-run, and `check-upstream` commands are serialized. The lock records the\nhost, platform, and process start identity. A lock from another runtime (for\nexample Windows versus WSL), or one whose owner cannot be verified, is left in\nplace and the command explains how to inspect and remove it after confirming\nthat no sync is running.\n\nWrites and removals are staged and journaled before the target is changed; an\nordinary failure rolls the whole refresh back. If the process is interrupted,\nthe next `--apply` recovers the unfinished transaction before rebuilding the\nsync plan. If a user changed a target during an unfinished rollback, mstack\nmoves that file to `.mstack-sync-upstream/recovery/<transaction>/<index>.user`\nand restores the previous version; the command prints both paths. A\n`COMMITTED` marker is authoritative, so later user edits are preserved while\ntransaction sidecars are cleaned up. Dry runs and `check-upstream` refuse to\ninspect a target while a sync is active or needs recovery.\n\nOn Windows, directory fsync is best-effort because Node cannot portably flush a\ndirectory handle. The transaction provides process-crash recovery, but it does\nnot provide a power-loss durability guarantee on that platform. Readers that\nignore the sync lock can still observe files changing during the commit.\n\n`--apply` writes `profiles/upstream-manifest.json`. Its artifact hashes describe\nthe transformed upstream baseline, while `canonicalSkills` records the pinned\nsource body and reviewed target body for each canonical skill. Files configured with\n`compareContent: false`, including the adapted agents, may intentionally differ\nfrom those hashes. A different checkout can be used as the destination with\n`--target /path/to/mstack`.\n\n## Verify changes\n\nRun the complete local check before you commit:\n\n```bash\nnpm test\n```\n\nThe check validates the canonical tree and runs installer, context, upstream\nsync, runtime, and environment tests.\n\n## Add a skill\n\n1. Add `skills/<name>/SKILL.md` with `name` and `description` frontmatter.\n2. Keep the main file portable. Put harness-specific paths and commands in a\n   reference file.\n3. Add the skill name to `profiles/skills.json`.\n4. Add adapter metadata only when a harness needs it.\n5. Run `npm test` and verify discovery in at least one supported harness.\n\nUse the same name for a skill in the canonical tree, adapters, tests, and docs.\nThis keeps installation and validation data-driven.\n\n## License\n\nmstack is released under the MIT License. See\n[`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md) for upstream licenses and\nsource revisions.\n","readmeFilename":"README.md"}