@devenius/junamis-skills 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+## [1.1.0] - 2026-11-13
+
+### Added
+- `.github/workflows/publish.yml` is renamed to `Publish` and runs two jobs: `publish-github` mirrors to GitHub Packages with `GITHUB_TOKEN` and `packages: write`, and `publish-npm` stages to npmjs with OIDC (`id-token: write`), the `npm-publish` environment, and `npm stage publish`. The npm job sets no `NODE_AUTH_TOKEN`; a maintainer approves the staged version on npmjs.com. Top-level permissions are `contents: read` and each job adds only what it needs.
+- `pnpm publish:npm` (`scripts/publish-npm.mjs` over `src/scripts/publish-npm.ts`) is a read-only publish checklist. It validates the package name, `publishConfig.access`, and the absence of `publishConfig.registry`, then prints the exact `npm stage publish` command. It never runs a registry mutation.
+- `src/color.ts` is a dependency-free ANSI helper (`paint`, `createColors`, `stripAnsi`, `colorsEnabled`). The `init` and `status` CLI output and the release gate use it: cyan headers, green success, yellow warnings, red errors, and gray details. Color disables itself for a non-TTY stream, `NO_COLOR`, or `TERM=dumb`, so captured output stays plain.
+- Every orchestrator prompt starts with `git branch --show-current`. On `main` or a detached HEAD it runs `git fetch origin` and `git switch -c task/<task-slug> origin/main` (or `git switch -c task/<task-slug> main` when there is no remote) and continues on that branch. On a task branch it continues; it never works on `main`. The orchestrator commits on `task/<task-slug>` in the project checkout, where the state root (`<project>/.orchestrator/`) and the design registry (`<project>/docs/design/`) live.
+- The orchestrator plans the delegation in `<state-root>/delegation.md` with one row per task: owner, depends on, worktree, branch, allowed files, and done proof. Every file has exactly one owner, and dependency order is explicit.
+- Each delegated task runs in `<project>/.worktrees/<task-slug>-<subtask>` on `task/<task-slug>-<subtask>`, cut from the task branch. The brief names the absolute path, the branch, and the allowed files. The sub-agent edits only its allocated files, asks the orchestrator for any file outside the allocation, never creates a pull request, and may commit only its allocated files on its assigned sub-branch.
+- When a sub-agent finishes, the orchestrator verifies the diff is a subset of the allowed files, runs the task checks, merges with `git merge --no-ff`, removes the worktree with `git worktree remove`, and deletes the merged sub-branch with `git branch -d`. On conflict it runs `git merge --abort`, stops, and asks the user.
+- One pull request per approved batch, and orchestrator prompt version 2.0.0. After every task is merged and the full gate passes, the orchestrator asks the user to approve, pushes `task/<task-slug>`, opens the pull request with `gh pr create`, reports the URL, and stops. The user reviews and merges; the agent's authority still ends at `gh pr create`.
+- Worktree limit is 8. Before creating one the orchestrator counts `git worktree list` entries under `<project-root>/.worktrees/` and prunes only a worktree that is merged into the task branch and clean, with `git worktree remove` (never `rm -rf`); if none qualifies it asks the user.
+- `opencode.json` allows external directories under `/tmp/**`, `/var/tmp/**`, `.worktrees/**`, and `**/.worktrees/**`, and allows the worktree shell workflow (`git status`, `git diff`, `git fetch`, `git branch --show-current`, `git switch -c task/*`, `git checkout -b task/*`, `git merge --no-ff task/*`, `git merge task/*`, `git merge --abort`, `git worktree add|list|remove`, `git add`, `git commit`, `git push origin task/*`, `pnpm install|test|build|typecheck|lint`, `pnpm run check:*`, `node --test`, `npx tsc`, the `npx --package` fallbacks for `junamis-orchestrator`, `junamis-design-registry`, and `junamis-reconcile`, and the GitHub pull-request commands `gh pr create|view|list|checks|edit` plus `gh run list|view|watch`).
+- The design registry bootstrap now always writes the project-wide map at `docs/design/other/project.md` (`surface_id: other/project`, kind `other`, `code_paths: []`, draft, owner `library/document`). It names the project, lists every discovered target as workspace, kind, surface_id, and code_paths, and is included in the bootstrap result and the regenerated `INDEX.md`. An existing map is never rewritten.
+- `## Environment setup` in the orchestrator prompt. Before `boot`, `route`, or any dispatch the orchestrator resolves the project root as the user's cwd, checks the four installed library files, ensures the state CLI, checks the four required design registry files (`_schema.md`, `INDEX.md`, `_registry.json`, `other/project.md`), and bootstraps a missing registry only after asking once. A declined bootstrap continues with `design_context: none` and records the missing registry.
+- `docs/RECONCILE.md` is installed as a shared doc next to `RESUME.md` and is published in the package file set.
+- The orchestrator's authority now ends at `gh pr create` (prompt version 1.5.0). After pushing `task/<task-slug>` it opens the pull request, reports the URL, and stops. It never merges, never uses `--admin`, never pushes `main`, never force-pushes, never tags, and never rebases or resets `main`; every action that touches `main` belongs to the user, who reviews and merges.
+- Approvals are single-use, stated in the orchestrator prompt, `AGENTS.md`, and `CONTRIBUTING.md`: one command in one prompt exactly once, ended when that command finishes or fails, never reused for a retry, a second command, a later step, another task, another pull request, or another session, and asked again every time.
+- `.github/pull_request_template.md` checklist items record that the pull request was created by the agent and not merged by it, that `main` was not pushed, and that every approval used in the task was single-use.
+- `test/orchestrator-policy.test.js` locks the PR-only authority and the single-use approval wording across the orchestrator prompt, `AGENTS.md`, `CONTRIBUTING.md`, and the pull request template.
+
+### Changed
+- Hard-deny policies now also deny `shell:gh pr merge` (bare), `shell:git push origin main *`, `shell:git push origin HEAD:main`, and `shell:git push --force-with-lease *`. `git push origin task/*`, `git push -u origin task/*`, and `gh pr create *` stay allowed, and `HARD_DENY_POLICIES` in the config check mirrors the new denies.
+- Hard-deny policies now also deny `shell:git switch main`, `shell:git checkout main`, `shell:git branch -d main`, and `shell:git branch -D main`, so the orchestrator cannot leave a task branch for `main`. `HARD_DENY_POLICIES` in the config check mirrors them, and `git switch -c task/*` and `git checkout -b task/*` stay allowed.
+- Hard-deny policies replace the blanket `shell:git push *` with targeted denies: `shell:git push origin main`, `shell:git push --force *`, `shell:git push -f *`, `shell:git commit --no-verify *`, and `shell:gh pr merge *`. Pushing a `task/*` branch and opening or checking a pull request are allowed; every other hard deny is unchanged.
+- The orchestrator never skips a state or design step because a bin is missing. It prefers `junamis-orchestrator` and `junamis-design-registry` on `PATH` and falls back to `npx --yes --package github:devenius/junamis-skills#main ...`; the package `prepare` script builds `dist/` for that fallback.
+- The orchestrator must call `start` before every dispatch, `end` after it, and close every session with `checkpoint` plus `finish` or `lease release`. A task with no `start`/`end` is not a completed run.
+- `RESUME.md` reference implementation documents the `npx --package` fallback for the state CLI; the normative contract is unchanged.
+
+### Fixed
+- Git installs (`npx github:...`) now build `dist/` through the `prepare` script, so the bin can load the CLI.
+
+## [1.0.0] - 2026-11-10
+
+### Added
+- `library/RESUME.md` as the normative persistence and resume contract. It is installed as a shared doc next to `HANDOFF.md`, `SAFETY.md`, `EXTERNAL.md`, and `SECURITY.md`.
+- `src/orchestrator/` and the `junamis-orchestrator` bin (`scripts/orchestrator-state.mjs`): a journal-first state engine with `boot`, `plan set`, `plan show`, `start`, `end`, `resolve`, `status`, `checkpoint`, `lease acquire|heartbeat|release|status`, and `finish`.
+- The default state root `<project>/.orchestrator/` (gitignored), with an append-only hash-chained `journal.ndjson`, derived `state.json`, `plan.json`, and `tasks/<task_id>/task.json`, checkpoints, a single-writer lease, `resume-report.md`, and the generated `STATE.md` view.
+- `idempotent: true | false` frontmatter on all 19 library skills. An interrupted `true` step retries; an interrupted `false` step becomes `needs_review`. The `route-external` adapter records the external value and defaults to `false` when upstream does not declare one.
+- `skills-lock.json` is installed as shared data at the config root so the installed engine can fingerprint the manifest.
+- T1 to T7 integration coverage: crash injection, replay determinism with and without a checkpoint, manifest and override drift, lease safety and stale takeover, non-idempotent escalation, and torn-write recovery, with a fixture project under `test/fixtures/orchestrator/project/`.
+- Renamed the package to `@devenius/junamis-skills` and the binary to `junamis-skills` (`bin/junamis-skills.js`). The guide is now `junamis-skills-guide.md` and the project marker `.junamis/junamis-skills.json`.
+- Adopted the nested config layout: config root `~/.config/junamis/skills/`, internal skills in `.../skills/skills/<name>/SKILL.md`, canonical agents in `.../skills/agents/<name>.md`, shared docs in `.../skills/*.md`, and the manifest in `.../skills/installed/library-<agent>.json`. Project scope mirrors this under `<project>/.config/junamis/skills/`.
+- Agent definitions are written once to the canonical agents directory and symlinked into each target's agents directory. An identical regular file is adopted, a differing file or wrong symlink is a conflict unless `--force`, and a failed symlink falls back to a copy with a warning.
+- `status` reports each canonical agent and whether its target link is correct, and reports legacy flat files as informational.
+- `src/paths.js` is the single source of truth for the config root and install paths.
+- `init` now installs everything in one non-interactive run: the guide, `opencode.json` for OpenCode (when missing or with `--force`), the library, and every pinned external skill. Injected dependencies make `init` testable without network access.
+- `SECURITY.md` as the recorded scan record for all 19 internal and 24 external skills: kind, source, license, scan status, last review month, and the pinned scanner. It is published, installed as a shared doc, and enforced by `check:security` in CI and `release:check`.
+- `status` replaces `doctor` and reports the guide, marker, per-target internal/external skill counts, library manifest validity, config validity, external coverage, and the `SECURITY.md` scan record. It exits 1 only when a detected target's manifest or config is invalid, or project JSON is malformed.
+- Added the `route-external` internal skill, owned only by the orchestrator, which writes `.junamis/adapters/<skill>.md` so external skills report through the HANDOFF contract without editing upstream content.
+- Added the design registry CLI (`scripts/design-registry.mjs`, `src/design/`) with a strict dependency-free frontmatter and delta parser, kind schemas for `web`, `api`, `data`, `infra`, `cli`, and `other`, required common and kind-specific sections, and a body-only SHA-256 `design_checksum`.
+- Design registry writes use the state engine's atomic protocol through `src/design/atomic.js`: temp file, fsync, rename, and parent-directory fsync.
+- Design deltas are applied mechanically by `applyDelta`: `replace`, `append`, `prepend`, and `remove_line` only, with a base-checksum concurrency guard, automatic version bump, review metadata updates, an append-only change log, full re-validation, an atomic write, and `design_update` / `design_delta_rejected` journal events. A rejected delta also marks its task `needs_review`.
+- `INDEX.md` is generated from frontmatter only: sorted by `surface_id`, gap counts from `## Known gaps`, status counts, and a `Generated` timestamp derived from the newest `last_reviewed` date (or `--generated-at`) so identical input is byte-identical output.
+- Design drift detectors cover code drift by `last_reviewed_commit` or mtime fallback, dependency drift from the dependent surface's change log, and coverage overlaps plus unclaimed source files. Coverage failure is gated by `docs/design/_registry.json` `bootstrap_complete`; overlaps are always reported.
+- Added the internal `document` janitor skill, owned by the orchestrator, as the override of the external `document` capability. It may reorganize and reconcile the registry but may not introduce facts that are not already in deltas or code, and it may not promote drafts.
+- Added `design-registry bootstrap`: a one-shot scan of `src/`, `bin/`, and `scripts/` that drafts one `other` surface per source file, writes the canonical `web/homepage` and `api/get-user` examples, creates `docs/design/_registry.json` with `bootstrap_complete: false`, and never promotes a draft.
+- `RESUME.md` B4 now fingerprints the design registry as `design_registry: { index_sha256, surface_count, status_counts }` in `state.env_fingerprint`. A mismatch is `BLOCKED_DRIFT` with a design diff; a missing recorded value is a one-time `design_baseline` instead of a block. `last_reviewed_commit` is an optional frontmatter extension used for code drift.
+- Added design contract tests D-T1 to D-T8: schema validation, byte-stable INDEX, idempotent deltas, stale checksum rejection with `needs_review`, code drift in a temporary git repo, gated coverage, deprecated-surface rejection, and B4 `BLOCKED_DRIFT` with a design diff.
+- Adopted `docs/design/_schema.md` as the normative design registry contract. It defines the surface layout, required frontmatter and sections, the `design_delta` shape, drift model, atomic write protocol, generated index, and D-T1 to D-T8 acceptance tests.
+- Exposed `junamis-design-registry` as a package bin for `scripts/design-registry.mjs`, and completed the CLI with `index --check` for CI byte comparison and a `fingerprint` command for the B4 design fingerprint.
+- Design registry bootstrap now resolves the project from `<cwd>` and writes `<cwd>/docs/design`: one draft overview for a single project, or one per app/package for a monorepo, with the kind detected from dependencies, `bin`, and conventional directories. It copies `_schema.md`, creates `_registry.json`, and never creates the package's `web/homepage` or `api/get-user` examples. `load --code-path` returns matching surfaces and checksums for dispatch context. The package publishes `docs/design/_schema.md` so an installed bootstrap can copy it into a project.
+- Added the RECONCILE pass A work queue: `plan_pending`, `code_drift`, and `failed_step` detectors from `$ORCH_STATE_ROOT/reconcile/detectors.yaml`; fixed scoring; dedupe and dependency closure; deterministic `work-queue.json` and `reconcile-report.md`; and `reconcile_pass` journal events. B7.5 runs it at boot, every `step_end` and `drift_detected` triggers it, and `junamis-reconcile pass --trigger design_delta_rejected` exposes the design rejection path. The queue is derived and never writes the design registry or plan.
+- Completed RECONCILE pass B: `coverage_gap`, `dependency_drift`, `needs_review`, `stale_surface`, and `shadow_conflict` detectors; full scoring with `plan_position_frac`; priority overrides with audit rejection; periodic tick; and the remaining journal events (`queue_blocked`, `queue_stale`, `unknown_reason`, `run_stalled`, `priority_override`, `priority_override_rejected`). Escalation now distinguishes blocked heads, shadowed heads, all-done `run_complete`, and stalled queues with a blocking set.
+- Added the strict TypeScript toolchain: `typescript`, `@types/node`, and `@types/js-yaml` as dev dependencies (no runtime dependency), `tsconfig.json` for type-only checking, and `tsconfig.build.json` emitting JavaScript, declarations, and source maps to `dist/`. `dist/` stays generated and gitignored, and ESLint ignores it and the TypeScript sources because `tsc` gates them.
+- All runtime code is now TypeScript under `src/**/*.ts`: the installer, targets, guide, pinned source, external install, library install, the orchestrator state engine, the design registry, the reconcile pass, and the dev checks. The published package ships only the built `dist/` output and its `.d.ts` declarations; `src` is no longer in `files`.
+- The consumer contract is `main: dist/index.js`, `types: dist/index.d.ts`, and the `.` / `./types` `exports` subpaths, all pointing at `dist/`. `bin/junamis-skills.js`, `scripts/orchestrator-state.mjs`, `scripts/design-registry.mjs`, `scripts/reconcile.mjs`, and every `scripts/check-*.mjs` launcher import from `dist/` and hold no logic.
+- Strict types throughout: the settings in `tsconfig.json` are fixed, object shapes are `interface` and unions are `type`, snapshot fields are `readonly`, no `any` is used, and every external input (JSON, YAML, argv, environment, journal lines, handoff blocks, design frontmatter) stays `unknown` until a runtime guard or module validator proves its shape.
+- Added `src/types/` as the single type contract: `common`, `handoff`, `orchestrator`, `design`, and `reconcile` interfaces, runtime guards (`isRecord`, `isString`, `isStringArray`, `isOneOf`, `assertNever`, `errorMessage`, `parseJsonUnknown`), a barrel, and a convention README. Object shapes are `interface`, unions are `type`, snapshot fields are `readonly`, external input is `unknown` until guarded, and no `any` is used.
+- Added `src/index.ts` as the package entry, `tsconfig.types.json` with `test/types/consumer.ts` as the compiled consumer contract, and the `build`, `typecheck`, `prepack`, and updated `test` scripts. The package exposes `main`, `types`, and the `.` and `./types` exports for `dist/`; `files` includes `dist` and excludes `src`, and `check:pack` requires the built entries, declarations, CLIs, and launchers.
+- CI runs `pnpm build` before every check that imports from `dist/` and before `pnpm test`, and also runs `pnpm typecheck`. The release and publish workflows build through `prepack` and `release:check`, so the packed artifact always contains `dist/`.
+- Added `docs/typescript.md` and the AGENTS.md TypeScript rules covering the build outputs, the consumer entry, `unknown` at boundaries, guards, and the dist-only package rules.
+- 1.0.0 is the first release built from a fresh repository: all runtime code is TypeScript under `src/**/*.ts`, the published package is the built `dist/` output plus its `.d.ts` declarations, and `prepack` rebuilds `dist/` before a tagged release is packed.
+- Added `## Branch and pull request policy` to `AGENTS.md`, a `.github/pull_request_template.md`, and `CONTRIBUTING.md`: `main` is read-only, every change goes on a task branch/worktree, and `main` receives work only through a reviewed pull request.
+- Added `## Work isolation` to the orchestrator prompt: a read-only request may run anywhere, but any write, git, or state-root action establishes a task branch/worktree from the default branch first, pushes the branch, and opens a pull request before stopping for approval.
+- Added `test/orchestrator-simulation.test.js`, a hermetic end-to-end run of the built CLIs: design bootstrap, `boot` (`NEW_RUN`), `plan set`, a `plan_pending` reconcile head, `start`, a complete handoff and artifact, `end`, and a final reconcile to `no_work` with `run_complete`.
+- Added `docs/releases/1.0.0.md`: the release notes for this version.
+
+### Security
+- The shipped `opencode.json` allows the first-party state engine command without a shell prompt while every other shell command still asks and the secret denies and hard-deny policies still apply.
+- Execution state is host-local under `<project>/.orchestrator/`, gitignored, created with owner-only modes, and guarded against a state root inside the operating system temp directory or at the filesystem root.
+- A single-writer lease prevents two sessions from writing one state root. A live lease halts the second session; a stale lease is taken over and journaled.
+- Manifest and library override drift is a correctness gate: boot, `plan set`, and `start` refuse to dispatch and report the exact changed hashes and paths.
+- The state engine adds no runtime dependency and uses only Node 26 built-in modules. `js-yaml` stays a dev dependency for `scripts/check-yaml.js` only.
+- The handoff validator is a strict parser for the documented block and rejects unsafe artifact paths with realpath containment; a malformed handoff is quarantined as `needs_review`, never executed.
+- Keep link destinations inside a managed root by checking their parent directory, so a wrong symlink target is reported as a conflict instead of being followed. Canonical link targets must also resolve inside a managed root. Existing realpath, symlink, and ENOTDIR protections are unchanged.
+- Always pass `--skip-scan` to the pinned scanner. `-y` does not bypass its high/critical "Install anyway?" prompt; a real run prompted on four source groups and silently left skills uninstalled while counting them. Install-time scanning is skipped by design, and `SECURITY.md` plus `library/SAFETY.md` is the vetting record.
+- After each successful scanner group, verify that every expected `<name>/SKILL.md` exists under the target's global skills directory. Only verified skills count as installed; an already-present skill is skipped; a skill missing after a successful run is a logged failure.
+- Allow an in-tree symlink inside a verified skill tree (for example `CLAUDE.md -> AGENTS.md`) while still rejecting absolute targets, targets that escape the skill folder, and gitlinks. This unblocks `agent-rules`.
+- Correct the `driftlock` tree SHA to `6c4a9e981e2d8abc0f2bb557b4c84672cb5701a9` and add `check:pins` to re-fetch each locked source/ref and compare the actual tree SHA with the lock.
+- Record the observed HIGH/CRITICAL findings for `develop`, `nestjs-best-practices`, `shadcn`, `shadcn-component-discovery`, `skill-creator`, `webapp-testing`, `mcp-builder`, `agent-rules`, `driftlock`, and `agent-browser` as `flagged` in `SECURITY.md`, with the gate in `library/SAFETY.md`.
+- Pin the skillsio scanner to the public npm registry with a verified tarball integrity hash and tarball URL, and run it from a neutral working directory with a sanitized environment.
+- Reject project library manifests whose managed roots or targets resolve through a symlink outside the project, using real paths rather than lexical containment alone.
+- Validate project library manifests before use: absolute paths inside the managed roots, well-formed hashes, no duplicates, and no symlinked targets.
+- Reject planned library destinations that resolve through a symlinked root or subdirectory outside the managed roots before writing anything, even when no manifest exists, the manifest is empty, or `--force` is given.
+- Treat `ENOTDIR` like `ENOENT` and reject a regular file at a managed root with a clean `managed root is not a directory` error instead of a raw crash.
+- Allow a global managed root symlinked to another directory inside the home directory, while still rejecting roots that escape home.
+- Change the shipped `opencode.json` bash default from `allow` to `ask`, and deny reads of `.git/config` and `.git/modules/*`.
+- Pass `-y` to the pinned scanner so `init` can install non-interactively. The scan is still never skipped, and declined-scan output is still converted to a failure.
+- Require the pinned skill path to be a Git tree, rejecting symlinks and gitlinks inside it.
+- Verify that the checkout HEAD equals the locked commit after fetching.
+- Terminate timed-out child processes by process group and only settle after the child closes.
+- Cap captured child output at 64 KiB and keep the tail for diagnostics.
+- Remove plaintext HTTP and user-content hosts from the `webfetch` allowlist.
+- Pin every GitHub Action to a full commit SHA in all workflows.
+- Override the dev-only `minimatch` advisory to a patched version.
+- Ignore `.npmrc`, `.env*`, and `.junamis/` in Git.
+- Strip ANSI CSI/OSC control sequences from installer output before forwarding it.
+- Assert the documented `opencode.json` invariants in the config check.
+- Enable pnpm's minimum release age and remove the unused exclusion.
+- Remove the unused `computedHash` field from the skill lock.
+- Validate project-supplied JSON in `status` and `doctor` and report malformed input without crashing.
+
+### Changed
+- The published package ships only `docs/design/_schema.md` from `docs/`: the bootstrap copies that schema into a project, while internal `docs/research`, `docs/reviews`, the design registry examples, and the release notes stay out of the packed set. npm would otherwise include the sibling `docs/design/README.md`, so `files` excludes it explicitly. `files` stays dist-first and still excludes `src`.
+- The 1.0.0 changelog is consolidated into this single section: the earlier 2026-10-31 section is removed and `docs/releases/1.0.0.md` mirrors this section for the GitHub Release.
+- The package's own design registry is now small and per project: `cli/overview` is the real single-project bootstrap overview (`package.json` has `bin`, so kind detection resolves `cli`) and `web/homepage` plus `api/get-user` remain the canonical schema examples. The 53 per-file `src-*`, `scripts-*`, and `bin-*` drafts were removed, `INDEX.md` was regenerated, and D-T1 asserts the canonical surfaces instead of the old 55-file scan.
+- The package is dist-only: `src` is removed from `files`, `dist/` and its declarations are the published runtime, every bin and check launcher imports `dist/`, and `check:pack` fails if any `src/` path or nested upstream clone appears in the packed set. The orchestrator now imports the shared `PACKAGE_ROOT` from `src/guide.ts`, and the transitional `src/guide.js` bridge is deleted.
+- The orchestrator now boots before `route` on every session, reads `resume-report.md`, and stops on exit `2` (`lease_held`), `3` (`BLOCKED_DRIFT`), or `4` (`HALT_CORRUPT`). `NEW_RUN` uses a one task bootstrap plan with `plan set`; a later full graph uses `plan set --replace`. Every dispatch is wrapped by `start` and `end`, with `resolve` after a user decision and `checkpoint`/`finish`/`lease release` at the close.
+- `route` accepts the resume report as its first input and has a `resume` path that starts from the recorded cursor, `resolved_skill`, `resolution_source`, and `owner` without rescanning the request.
+- `HANDOFF.md` now references `RESUME.md`, declares schema version 1, explains idempotency, defines where the orchestrator persists a handoff block, and maps handoff statuses to task statuses.
+- `.gitignore` now ignores `.orchestrator/`. `package.json` exposes `junamis-orchestrator` as a bin and includes `scripts/orchestrator-state.mjs` in `files`.
+- Migrated the shipped `opencode.json` to OpenCode V2 (`permissions`, `policies`, `mcp.servers`, `plugins`). It enables the first-party file tools and local skills, keeps shell and network fetches gated, denies secret paths and `external_directory`, hard-denies destructive shell verbs, and ships with no MCP servers or third-party plugins. `check:config` now validates the V2 shape.
+- The shipped `opencode.json` registers `{env:HOME}/.config/junamis/skills/skills` and `{env:HOME}/.agents/skills`, with instructions at `{env:HOME}/.config/junamis/skills/*.md`. Project scope rewrites them to `./.config/junamis/skills/...`.
+- No automatic migration: `init` writes only the new layout. `status` reports old flat files under `~/.config/junamis/` and flat skill folders under `~/.config/junamis/skills/` as legacy and never deletes them.
+- Reduce the CLI to `init`, `status`, and `help`. `install-library`, `install-external`, `sync`, `doctor`, and `init-config` were removed; calling one now fails with `unknown command: <cmd>. Use "init" or "status".`
+- `init` installs every external skill automatically and treats already-installed skills as skipped, not failed. It exits 1 only when an external install reports a failure.
+- Split internal (library) skills from external skills for OpenCode: internal skills install to `~/.config/junamis/skills/skills`, canonical agents to `~/.config/junamis/skills/agents`, shared docs to `~/.config/junamis/skills/`, and the install manifest to `~/.config/junamis/skills/installed/library-<agent>.json`. External skills stay in `~/.agents/skills`, and `opencode.json` registers both skill roots. Other targets keep their single skills directory but share the canonical agents directory.
+- Remove the ignored `pnpm` field from `package.json`; `pnpm-workspace.yaml` is the single source of truth for overrides.
+- Use the platform null device from `node:os` for the scanner's config paths.
+- The orchestrator now routes both internal and external skills, wraps external skills through `route-external`, dispatches scoped sub-agents for unrelated work, and answers agent questions only within its own authority; user decisions stop the chain. Every specialist agent can pause and ask the orchestrator during work.
+- The handoff contract now reserves `## Suggested commit` for the orchestrator. At the end of every task the orchestrator records a proposed Conventional Commits message, the exact files, a one-line rationale, and a state; specialists never propose or run commits. When the user says "commit" without a message or scope, the orchestrator uses the suggestion, refreshes it if stale, and awaits the next decision.
+
+### Fixed
+- The release check builds the TypeScript output before running, so the release and publish workflows no longer start before `dist/` exists.
+- `init --dir <new>` no longer crashes with `ENOENT ... realpath` before planning. The managed-root check falls back to the lexical project path and `writeGuide` creates the project directory before writing, so a dry run prints the full plan without creating it and a real run installs into the new directory.
+- `status` is informational for targets that are not installed or detected, and for an absent per-project guide. It exits 1 only for a detected target with an invalid manifest/config, a malformed project marker, or malformed `opencode.json`.
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 junamis-skills contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,232 @@
-# Temporary Holding Version
+# junamis-skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An orchestrated set of Agent Skills and agents for AI coding tools. The package ships:
+
+- **The library** (`library/`): the orchestrator, eight specialist agents, and the skills they use.
+- **The manifest** (`skills-lock.json`): external skill sources, immutable commits, per-skill tree SHAs, and licenses.
+- **A scan record** (`SECURITY.md`): per-skill kind, source, license, scan status, and last scan month.
+- **An installer** (`junamis-skills`): one `init` command installs the library and every external skill, and writes a setup guide into your project.
+
+## Quick start
+
+Run these in the project that will use the skills. Use `--dry-run` first to see what will change. Requires Node.js 26+; external installs also require Git.
+
+The package name is `@devenius/junamis-skills`. The command-line binary it installs is `junamis-skills`. `npx @devenius/junamis-skills ...` runs the binary without a separate install.
+
+### Option A: Install from npmjs (primary)
+
+```bash
+# 1. Preview the whole install, then apply it.
+npx @devenius/junamis-skills@latest init --dry-run
+npx @devenius/junamis-skills@latest init
+
+# Or install the CLI globally and use the junamis-skills binary.
+npm install -g @devenius/junamis-skills@latest
+
+# 2. Check state.
+npx @devenius/junamis-skills@latest status
+```
+
+### npmjs status
+
+npmjs is the primary public registry. **Until `1.1.0` is published and approved on npmjs.com, `latest` still points at the `0.0.0-stage` placeholder**, so the commands above resolve to an empty placeholder, not a working installer. The first usable npm release is **`1.1.0`**.
+
+- **Until `1.1.0` is live on npmjs**, use the GitHub direct install in Option B. It is the safe path today.
+- **After `1.1.0` is live on npmjs**, the npmjs commands in Option A are primary and `latest` is `1.1.0`.
+
+The placeholder was staged from a separate release branch; it is not a banner on `main`.
+
+### Option B: Run directly from GitHub (no setup, safe today)
+
+```bash
+# 1. Preview the whole install, then apply it.
+npx github:devenius/junamis-skills init --dry-run
+npx github:devenius/junamis-skills init
+
+# For Claude Code instead of OpenCode:
+npx github:devenius/junamis-skills init --agent claude
+
+# Install into the project instead of globally:
+npx github:devenius/junamis-skills init --scope project
+
+# 2. Check state.
+npx github:devenius/junamis-skills status
+```
+
+`init` writes the setup guide, writes `opencode.json` when it is missing (OpenCode only), installs the library, and installs every pinned external skill. Use `--force` to overwrite a guide, config, or library file you edited.
+
+### Option C: Install from GitHub Packages (mirror)
+
+GitHub Packages is the mirror of npmjs. Configure `~/.npmrc` once (see [Installing from GitHub Packages](#installing-from-github-packages)), then use the normal npx form:
+
+```bash
+npx @devenius/junamis-skills init --dry-run
+npx @devenius/junamis-skills init
+npx @devenius/junamis-skills status
+```
+
+Then open the project in your agent and send your first request to `orchestrator`.
+
+## Commands
+
+The CLI has two working commands and `help`.
+
+| Command | What it does |
+|---|---|
+| `init [--agent opencode\|claude] [--scope global\|project] [--dir <path>] [--force] [--dry-run]` | In order: writes `junamis-skills-guide.md` and its marker; writes/refreshes `opencode.json` for OpenCode (only when missing, or with `--force`); installs the library; installs every pinned external skill non-interactively. Exits 1 only when an external install fails. |
+| `status [--dir <path>] [--scope global\|project\|all]` | Reports the guide, marker, per-target internal/external skill counts, canonical agents and link state, legacy leftovers (informational), library manifest validity, `opencode.json` validity, external skill coverage, and the `SECURITY.md` scan record. Exits 1 only when a detected target's manifest or config is invalid, or project JSON is malformed. Default scope: `global` (matching `init`). |
+| `help` | Prints usage. |
+
+## Supported agents
+
+| Agent (`--agent`) | External skills directory | Internal (library) skills directory | Agent definitions (canonical → link) | External install support |
+|---|---|---|---|---|
+| `opencode` | `~/.agents/skills` | `~/.config/junamis/skills/skills` | `~/.config/junamis/skills/agents` → `~/.config/opencode/agents` | `skillsio` |
+| `claude` | `~/.claude/skills` | `~/.claude/skills` | `~/.config/junamis/skills/agents` → `~/.claude/agents` | `skillsio` |
+| `cursor` | `~/.cursor/skills` | `~/.cursor/skills` | `~/.config/junamis/skills/agents` → `~/.cursor/agents` | Library only |
+| `windsurf` | `~/.codeium/windsurf/skills` | `~/.codeium/windsurf/skills` | `~/.config/junamis/skills/agents` → `~/.config/devin/agents` | Library only |
+| `cline` | `~/.cline/skills` | `~/.cline/skills` | `~/.config/junamis/skills/agents` → `~/.cline/agents` | Library only |
+
+Agent definitions are written once to the canonical directory and symlinked into the target's agents directory. If a link cannot be created (for example Windows without developer mode), the file is copied instead and a warning is printed.
+
+For OpenCode, the shipped `opencode.json` registers both skill roots, so internal and external skills resolve side by side. Other targets keep a single skills directory shared by both kinds.
+
+The shipped `opencode.json` uses OpenCode V2 keys. It enables the built-in file tools and local skills, keeps shell and network fetches behind `ask`, denies secret paths and `external_directory`, hard-denies destructive shell verbs, and ships no MCP servers or third-party plugins. Add MCP servers or plugins only after a reviewed decision.
+
+Library installation supports all five targets. Scanned external installation (`init`) currently accepts only OpenCode and Claude Code.
+The Windsurf target keeps project skills in the legacy `.windsurf/skills` directory and installs subagents using Devin's current `.devin/agents` format and locations.
+
+Other agents are added on request, one target file each under `src/targets/`.
+
+## Where things go
+
+- External skills: `<external skills directory>/<name>/SKILL.md`
+- Internal (library) skills: `<internal skills directory>/<name>/SKILL.md`
+- Canonical agents: `~/.config/junamis/skills/agents/<name>.md`
+- Agent links: `<target agents directory>/<name>.md` → the canonical file
+- Shared rules the agents read: `~/.config/junamis/skills/` (`HANDOFF.md`, `SAFETY.md`, `EXTERNAL.md`, `SECURITY.md`, `RESUME.md`, `RECONCILE.md`)
+- Installed manifest for the state engine: `~/.config/junamis/skills/skills-lock.json`
+- Install record: `~/.config/junamis/skills/installed/library-<agent>.json`
+- Project scope: `<project>/.config/junamis/skills/{skills,agents,*.md,installed}` mirrors the internal side. External skills stay at the target's project skills directory, and project agent links stay at its project agents directory.
+- Session state and the guide marker stay in `.junamis/` (`handoff.md`, `junamis-skills.json`).
+
+For OpenCode the split is: internal skills in `~/.config/junamis/skills/skills`, canonical agents in `~/.config/junamis/skills/agents`, shared docs in `~/.config/junamis/skills/*.md`, the install manifest in `~/.config/junamis/skills/installed/library-opencode.json`, links in `~/.config/opencode/agents`, and external skills in `~/.agents/skills`. Other targets keep one skills directory for both kinds.
+
+`init` writes only the nested layout. There is no automatic migration: older flat files under `~/.config/junamis/` and flat skill folders directly under `~/.config/junamis/skills/` are reported by `status` as legacy leftovers and are never deleted. Move or remove them yourself once the new install is verified.
+
+## Persistence and resume
+
+The orchestrator is resumable. Every session starts by rehydrating execution state from disk, before `route` or any skill dispatch:
+
+```bash
+junamis-orchestrator boot --project <cwd> --session <new id>
+```
+
+The `junamis-orchestrator` bin also exposes `plan set`, `plan show`, `start`, `end`, `resolve`, `status`, `checkpoint`, `lease acquire|heartbeat|release|status`, and `finish`.
+
+- **State root.** The default is `<project>/.orchestrator/` (gitignored). It holds `journal.ndjson` (the source of truth), `state.json`, `plan.json`, `tasks/<task_id>/`, `checkpoints/`, `locks/`, `resume-report.md`, and the generated `STATE.md` view. `ORCH_STATE_ROOT` overrides the location. The root must be persistent and host-local, never inside the operating system temp directory.
+- **Report first.** `boot` writes `resume-report.md`. Read it in full. Its status is `NEW_RUN`, `RESUMING`, `COMPLETE`, `BLOCKED_DRIFT`, or `HALT_CORRUPT`. Exit codes are `0` success, `1` usage or I/O, `2` lease held or lost, `3` drift, `4` corrupt state, and `5` invalid transition or handoff. On a non-zero exit, stop and report the halt line and report path; dispatch nothing.
+- **Single writer.** A lease under `locks/` prevents two sessions from writing one state root. A stale lease is taken over; a live lease halts the second session.
+- **Drift gate.** `skills-lock.json` and the library override map are fingerprinted at plan time. A manifest or `library/` change makes boot report `BLOCKED_DRIFT` and refuse to dispatch.
+- **Idempotent or escalate.** Every library skill declares `idempotent: true | false` in its frontmatter. An interrupted `true` step is retried; an interrupted `false` step becomes `needs_review` and waits for a user decision. An external skill records the value in its adapter and defaults to `false` when upstream does not declare one.
+- **Contract.** `RESUME.md` is installed with `HANDOFF.md`, `SAFETY.md`, `EXTERNAL.md`, `SECURITY.md`, and `RECONCILE.md` at the config root and is the normative persistence contract. `RECONCILE.md` is the work-queue contract that decides what runs next.
+
+The state engine lives under `src/orchestrator/`, uses only Node 26 built-in modules, and adds no runtime dependency.
+
+## External skills (manifest)
+
+These are installed from `skills-lock.json` into the agent's global skills directory.
+
+| Skill | Source | License |
+|---|---|---|
+| `agent-browser` | [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) | Apache-2.0 |
+| `agent-rules` | [netresearch/agent-rules-skill](https://github.com/netresearch/agent-rules-skill) | MIT OR CC-BY-SA-4.0 |
+| `architect` | [JavaScript-Mastery-Pro/skills](https://github.com/JavaScript-Mastery-Pro/skills) | MIT |
+| `check` | [JavaScript-Mastery-Pro/skills](https://github.com/JavaScript-Mastery-Pro/skills) | MIT |
+| `debug` | [JavaScript-Mastery-Pro/skills](https://github.com/JavaScript-Mastery-Pro/skills) | MIT |
+| `develop` | [JavaScript-Mastery-Pro/skills](https://github.com/JavaScript-Mastery-Pro/skills) | MIT |
+| `doc-coauthoring` | [anthropics/skills](https://github.com/anthropics/skills) | Apache-2.0 |
+| `document` | [JavaScript-Mastery-Pro/skills](https://github.com/JavaScript-Mastery-Pro/skills) | MIT |
+| `driftlock` | [KairosSignal/driftlock-agent-docs](https://github.com/KairosSignal/driftlock-agent-docs) | MIT |
+| `find-skills` | [vercel-labs/skills](https://github.com/vercel-labs/skills) | MIT |
+| `frontend-design` | [anthropics/skills](https://github.com/anthropics/skills) | Apache-2.0 |
+| `grill-me` | [mattpocock/skills](https://github.com/mattpocock/skills) | MIT |
+| `grill-with-docs` | [mattpocock/skills](https://github.com/mattpocock/skills) | MIT |
+| `mcp-builder` | [anthropics/skills](https://github.com/anthropics/skills) | Apache-2.0 |
+| `nestjs-best-practices` | [Kadajett/agent-nestjs-skills](https://github.com/Kadajett/agent-nestjs-skills) | MIT |
+| `scope` | [JavaScript-Mastery-Pro/skills](https://github.com/JavaScript-Mastery-Pro/skills) | MIT |
+| `shadcn` | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) | MIT |
+| `shadcn-component-discovery` | [mattbx/shadcn-skills](https://github.com/mattbx/shadcn-skills) | MIT |
+| `shadcn-component-review` | [mattbx/shadcn-skills](https://github.com/mattbx/shadcn-skills) | MIT |
+| `skill-creator` | [anthropics/skills](https://github.com/anthropics/skills) | Apache-2.0 |
+| `tdd` | [mattpocock/skills](https://github.com/mattpocock/skills) | MIT |
+| `test` | [JavaScript-Mastery-Pro/skills](https://github.com/JavaScript-Mastery-Pro/skills) | MIT |
+| `theme-factory` | [anthropics/skills](https://github.com/anthropics/skills) | Apache-2.0 |
+| `webapp-testing` | [anthropics/skills](https://github.com/anthropics/skills) | Apache-2.0 |
+
+Each lock entry pins an upstream commit and skill tree SHA. Maintainers should follow the [external skill review and pinning procedure](docs/external-skills-maintenance.md) when changing this manifest.
+
+## Security record (`SECURITY.md`)
+
+[`SECURITY.md`](SECURITY.md) is the recorded vetting record for every skill the package installs. It lists each internal skill and each locked external skill with its source, license, scan status (`first-party`, `pass`, or `flagged`), and the month it was last reviewed. Install-time scanning is skipped by design (`--skip-scan`); `SECURITY.md` plus `library/SAFETY.md` is the vetting record. `Last external scan` records when the pinned `skillsio 1.1.3` scan (Trust Hub, Socket, Snyk) was last recorded. `scripts/check-security.mjs` fails CI when a skill is added and not recorded, or when that line is missing. `pnpm run check:pins` re-fetches every locked source and confirms its tree SHA.
+
+## Installing from GitHub Packages
+
+This package is also published to GitHub Packages as `@devenius/junamis-skills`; it is the mirror of the npmjs release, not the primary registry.
+
+1. Create or edit `~/.npmrc` (or project `.npmrc`):
+
+```ini
+@devenius:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+```
+
+2. Install or run:
+
+```bash
+npm install -g @devenius/junamis-skills
+# or run without installing:
+npx github:devenius/junamis-skills init
+```
+
+A GitHub personal access token with `read:packages` (and `write:packages` for publishing) is required.
+
+## Maintainers: publishing
+
+npmjs (`@devenius/junamis-skills`) is the primary public registry and GitHub Packages is the mirror. The release mechanics, trusted publisher setup, staged approval, and deprecation policy live in [`docs/publishing/npm.md`](docs/publishing/npm.md).
+
+**The user runs every publish and deprecate command.** The agent prepares the exact command and the release metadata and stops there. It never runs `npm publish`, `npm stage publish`, `npm deprecate`, `npm unpublish`, `npm dist-tag`, `npm owner`, or `npm access`; those are user actions gated by `library/SAFETY.md` and single-use approvals.
+
+## Safety
+
+- The installer never runs a command through a shell. Every value is checked against a strict pattern before use.
+- The scanner is pinned to `skillsio@1.1.3` with a verified registry, tarball URL, and SHA-512 integrity. Each locked commit, tree SHA, and checkout HEAD is verified before it runs.
+- A skill folder must be a Git tree. An in-tree symlink such as `CLAUDE.md -> AGENTS.md` is allowed; an absolute or escaping symlink is rejected, as is a gitlink.
+- `init` passes `-y` and `--skip-scan` so it can install every skill non-interactively. `-y` cannot bypass the scanner's high/critical prompt, so install-time scanning is skipped by design; the recorded scan is the gate. After each group it verifies that every expected `<name>/SKILL.md` exists and counts only verified installs.
+- Flagged findings are vetted in `SECURITY.md` and gated in `library/SAFETY.md`.
+- Destructive or external actions in the library need your explicit approval. See `library/SAFETY.md`.
+
+## Development
+
+The runtime code is TypeScript under `src/`. The built package ships `dist/` and its declarations; `src/` is not part of the published package.
+
+```bash
+pnpm install    # dev dependencies only; there is no runtime dependency
+pnpm build      # tsc -> dist/ (JavaScript, declarations, source maps)
+pnpm typecheck  # source check, then the compiled consumer contract
+pnpm test       # build, typecheck, then the full Node test suite
+```
+
+Consumers import the package root (`@devenius/junamis-skills`) or the `./types` subpath; both resolve to `dist/`. `dist/` is generated and gitignored, so contributors never commit it. See [`docs/typescript.md`](docs/typescript.md) for the build outputs, strict compiler settings, and the `unknown`-at-the-boundary rules.
+
+`main` is protected and read-only. Work on a task branch in its own worktree, run the gate above, push the branch, and open a pull request; never push directly to `main` and never self-merge. See [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`.github/pull_request_template.md`](.github/pull_request_template.md) for the checklist.
+
+## Reporting issues
+
+If an external skill is missing or an install fails, open an issue at
+https://github.com/devenius/junamis-skills/issues with these details:
+version, Node version, agent, installer, failing skill, and the command output.
+
+## License
+
+MIT. The external skills keep their own licenses, listed in `skills-lock.json`.

package/SECURITY.md

@@ -0,0 +1,81 @@
+# Security and scan record
+
+Last updated: 2026-11-10
+Last external scan: 2026-10
+Scanner: skillsio 1.1.3 (Trust Hub, Socket, Snyk)
+
+This file is the recorded vetting record for every skill the package installs. It
+is published with the package and installed as a shared doc at
+`~/.config/junamis/skills/SECURITY.md`, next to `SAFETY.md`.
+The approval gate itself is in `library/SAFETY.md`.
+
+> **Install-time scanning is skipped by design (`--skip-scan`).** The scanner
+> prompts on high/critical findings and cannot be bypassed non-interactively, so
+> `init` does not scan at install. This file plus `library/SAFETY.md` is the
+> vetting record: `flagged` rows were scanned and reviewed by hand, and
+> `pnpm run check:pins` confirms every locked tree SHA.
+
+- **Kind `internal`**: written and owned by this project, under `library/skills/`.
+- **Kind `external`**: pinned in `skills-lock.json` and installed from upstream.
+  The source commit and the skill directory tree SHA are verified before the
+  pinned scanner runs.
+- **Scan `pass`**: no high or critical findings were reported on the recorded scan.
+- **Scan `flagged`**: high or critical findings were reported and reviewed by hand. The
+  review is accepted in `SAFETY.md`; re-run the scan when the skill updates.
+
+| Skill | Kind | Source | License | Scan | Last updated at | Notes |
+|---|---|---|---|---|---|---|
+| db-migrate | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| decision-record | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| dependency-upgrade | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| document | internal | junamis-skills | MIT | first-party | 2026-11 | internal janitor override; the external skill of the same name remains upstream |
+| deploy-verify | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| env-doctor | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| frontend | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| handoff | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| incident-response | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| nestjs | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| nextjs | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| perf-budget | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| refactor-safely | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| release-prep | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| research | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| rollback | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| route | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| route-external | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| security-audit | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| skill-author | internal | junamis-skills | MIT | first-party | 2026-11 | |
+| agent-browser | external | vercel-labs/agent-browser | Apache-2.0 | flagged | 2026-10 | reviewed and accepted per SAFETY.md; global install and browser download are gated |
+| agent-rules | external | netresearch/agent-rules-skill | MIT OR CC-BY-SA-4.0 | flagged | 2026-10 | reviewed and accepted per SAFETY.md; 7 scanner findings (subprocess, --force); verify-commands and force runs are gated |
+| architect | external | JavaScript-Mastery-Pro/skills | MIT | pass | 2026-10 | no high or critical findings at install |
+| check | external | JavaScript-Mastery-Pro/skills | MIT | pass | 2026-10 | no high or critical findings at install |
+| debug | external | JavaScript-Mastery-Pro/skills | MIT | pass | 2026-10 | no high or critical findings at install |
+| develop | external | JavaScript-Mastery-Pro/skills | MIT | flagged | 2026-10 | reviewed and accepted per SAFETY.md; HIGH sensitive-environment read in documented workflow, not executed by the install |
+| doc-coauthoring | external | anthropics/skills | Apache-2.0 | pass | 2026-10 | no high or critical findings at install |
+| document | external | JavaScript-Mastery-Pro/skills | MIT | pass | 2026-10 | no high or critical findings at install |
+| driftlock | external | KairosSignal/driftlock-agent-docs | MIT | flagged | 2026-10 | reviewed and accepted per SAFETY.md; 26 HIGH Python subprocess flags, shipped script read-only, tests and examples never run |
+| find-skills | external | vercel-labs/skills | MIT | pass | 2026-10 | no high or critical findings at install |
+| frontend-design | external | anthropics/skills | Apache-2.0 | pass | 2026-10 | no high or critical findings at install |
+| grill-me | external | mattpocock/skills | MIT | pass | 2026-10 | no high or critical findings at install |
+| grill-with-docs | external | mattpocock/skills | MIT | pass | 2026-10 | no high or critical findings at install |
+| mcp-builder | external | anthropics/skills | Apache-2.0 | flagged | 2026-10 | reviewed and accepted per SAFETY.md; reference examples use pip install, API keys, and rm -rf dist; not executed, credential access is gated |
+| nestjs-best-practices | external | Kadajett/agent-nestjs-skills | MIT | flagged | 2026-10 | reviewed and accepted per SAFETY.md; HIGH external URLs in SQL/doc examples, never executed |
+| scope | external | JavaScript-Mastery-Pro/skills | MIT | pass | 2026-10 | no high or critical findings at install |
+| shadcn | external | shadcn-ui/ui | MIT | flagged | 2026-10 | reviewed and accepted per SAFETY.md; HIGH external URLs/registries, any --force is gated |
+| shadcn-component-discovery | external | mattbx/shadcn-skills | MIT | flagged | 2026-10 | reviewed and accepted per SAFETY.md; registry/URL reads reviewed, no writes |
+| shadcn-component-review | external | mattbx/shadcn-skills | MIT | pass | 2026-10 | no high or critical findings at install |
+| skill-creator | external | anthropics/skills | Apache-2.0 | flagged | 2026-10 | reviewed and accepted per SAFETY.md; CRITICAL RCE/C2 scanner report in eval scripts; script execution is gated |
+| tdd | external | mattpocock/skills | MIT | pass | 2026-10 | no high or critical findings at install |
+| test | external | JavaScript-Mastery-Pro/skills | MIT | pass | 2026-10 | no high or critical findings at install |
+| theme-factory | external | anthropics/skills | Apache-2.0 | pass | 2026-10 | no high or critical findings at install |
+| webapp-testing | external | anthropics/skills | Apache-2.0 | flagged | 2026-10 | reviewed and accepted per SAFETY.md; CRITICAL subprocess/socket findings in with_server.py; server start and tests are gated |
+
+## Scope of this record
+
+- The internal skills are first-party code. They are covered by the package's
+  tests and by the destructive-command check in `pnpm test`.
+- The external scan record was produced when the pins in `skills-lock.json` were
+  installed. Re-run the scan and update `Last external scan` whenever a pin
+  changes.
+- `scripts/check-security.mjs` fails CI when a skill is added to either side and
+  is not listed here, or when the `Last external scan` line is missing.

package/bin/junamis-skills.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from "../dist/cli.js";
+
+run(process.argv.slice(2)).catch((error) => {
+  console.error(`error: ${error.message}`);
+  process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,59 @@
+import { writeGuide } from "./guide.js";
+import { installExternal } from "./external.js";
+import { planLibraryInstall, applyLibraryInstall } from "./library-install.js";
+import type { ExternalInstallResult, InstallScope, ScopeSelection, StatusLocation } from "./types/index.js";
+export interface CliArgs {
+    readonly command: string;
+    readonly force: boolean;
+    readonly dryRun: boolean;
+    readonly dir: string;
+    readonly agent: string;
+    readonly scope: string | null;
+}
+export type ConfigStatus = "written" | "unchanged" | "kept" | "would-write" | "would-replace";
+export interface OpencodeConfigResult {
+    readonly status: ConfigStatus;
+    readonly path: string;
+}
+export interface OpencodeConfigOptions {
+    readonly dir?: string;
+    readonly scope?: string;
+    readonly force?: boolean;
+    readonly dryRun?: boolean;
+    readonly packageRoot?: string;
+}
+export declare function writeOpencodeConfig({ dir, scope, force, dryRun, packageRoot, }?: OpencodeConfigOptions): Promise<OpencodeConfigResult>;
+/** Injectable dependencies, so tests never touch the network. */
+export interface InitDeps {
+    readonly writeGuide?: typeof writeGuide;
+    readonly writeOpencodeConfig?: typeof writeOpencodeConfig;
+    readonly planLibraryInstall?: typeof planLibraryInstall;
+    readonly applyLibraryInstall?: typeof applyLibraryInstall;
+    readonly installExternal?: typeof installExternal;
+    readonly packageVersion?: () => Promise<string>;
+}
+export interface InitArgs {
+    readonly agent?: string;
+    readonly scope?: string | null;
+    readonly dir: string;
+    readonly force: boolean;
+    readonly dryRun: boolean;
+}
+/** The external install tally plus the dry-run count. */
+export interface InitExternalSummary extends ExternalInstallResult {
+    readonly planned?: number;
+}
+export interface InitResult {
+    readonly exitCode: number;
+    readonly scope: InstallScope;
+    readonly external: InitExternalSummary;
+}
+/**
+ * Run `init` with injectable dependencies so tests never touch the network.
+ * deps may override writeGuide, writeOpencodeConfig, planLibraryInstall,
+ * applyLibraryInstall, installExternal, and packageVersion.
+ */
+export declare function runInit(args: InitArgs, deps?: InitDeps): Promise<InitResult>;
+export declare function statusLocations(agentId: string, scope?: ScopeSelection, projectDir?: string): StatusLocation[];
+export declare function run(argv: readonly string[]): Promise<InitResult | number | undefined>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAKA,OAAO,EAAyC,UAAU,EAAE,MAAM,YAAY,CAAC;AAE/E,OAAO,EAAE,eAAe,EAAoC,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAgB,MAAM,sBAAsB,CAAC;AAG7F,OAAO,KAAK,EACV,qBAAqB,EAGrB,YAAY,EAGZ,cAAc,EACd,cAAc,EACf,MAAM,kBAAkB,CAAC;AAkC1B,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAmGD,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,aAAa,GAAG,eAAe,CAAC;AAE9F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID,wBAAsB,mBAAmB,CAAC,EACxC,GAAmB,EACnB,KAAgB,EAChB,KAAa,EACb,MAAc,EACd,WAA0B,GAC3B,GAAE,qBAA0B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA6B5D;AA0DD,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,UAAU,CAAC;IACxC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,mBAAmB,CAAC;IAC1D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,kBAAkB,CAAC;IACxD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,mBAAmB,CAAC;IAC1D,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,eAAe,CAAC;IAClD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAoB,SAAQ,qBAAqB;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,GAAE,QAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAoFtF;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,cAAsB,EAC7B,UAAU,GAAE,MAAsB,GACjC,cAAc,EAAE,CAkBlB;AAwND,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC,CAkB3F"}