@devenius/junamis-skills 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (311) hide show
  1. package/CHANGELOG.md +150 -0
  2. package/LICENSE +21 -0
  3. package/README.md +231 -2
  4. package/SECURITY.md +81 -0
  5. package/bin/junamis-skills.js +7 -0
  6. package/dist/cli.d.ts +59 -0
  7. package/dist/cli.d.ts.map +1 -0
  8. package/dist/cli.js +564 -0
  9. package/dist/cli.js.map +1 -0
  10. package/dist/color.d.ts +40 -0
  11. package/dist/color.d.ts.map +1 -0
  12. package/dist/color.js +55 -0
  13. package/dist/color.js.map +1 -0
  14. package/dist/design/atomic.d.ts +4 -0
  15. package/dist/design/atomic.d.ts.map +1 -0
  16. package/dist/design/atomic.js +14 -0
  17. package/dist/design/atomic.js.map +1 -0
  18. package/dist/design/bootstrap.d.ts +23 -0
  19. package/dist/design/bootstrap.d.ts.map +1 -0
  20. package/dist/design/bootstrap.js +411 -0
  21. package/dist/design/bootstrap.js.map +1 -0
  22. package/dist/design/cli.d.ts +86 -0
  23. package/dist/design/cli.d.ts.map +1 -0
  24. package/dist/design/cli.js +425 -0
  25. package/dist/design/cli.js.map +1 -0
  26. package/dist/design/delta.d.ts +45 -0
  27. package/dist/design/delta.d.ts.map +1 -0
  28. package/dist/design/delta.js +557 -0
  29. package/dist/design/delta.js.map +1 -0
  30. package/dist/design/drift.d.ts +26 -0
  31. package/dist/design/drift.d.ts.map +1 -0
  32. package/dist/design/drift.js +341 -0
  33. package/dist/design/drift.js.map +1 -0
  34. package/dist/design/errors.d.ts +25 -0
  35. package/dist/design/errors.d.ts.map +1 -0
  36. package/dist/design/errors.js +30 -0
  37. package/dist/design/errors.js.map +1 -0
  38. package/dist/design/events.d.ts +18 -0
  39. package/dist/design/events.d.ts.map +1 -0
  40. package/dist/design/events.js +44 -0
  41. package/dist/design/events.js.map +1 -0
  42. package/dist/design/fingerprint.d.ts +10 -0
  43. package/dist/design/fingerprint.d.ts.map +1 -0
  44. package/dist/design/fingerprint.js +66 -0
  45. package/dist/design/fingerprint.js.map +1 -0
  46. package/dist/design/index-gen.d.ts +16 -0
  47. package/dist/design/index-gen.d.ts.map +1 -0
  48. package/dist/design/index-gen.js +94 -0
  49. package/dist/design/index-gen.js.map +1 -0
  50. package/dist/design/schema.d.ts +54 -0
  51. package/dist/design/schema.d.ts.map +1 -0
  52. package/dist/design/schema.js +408 -0
  53. package/dist/design/schema.js.map +1 -0
  54. package/dist/design/yaml.d.ts +12 -0
  55. package/dist/design/yaml.d.ts.map +1 -0
  56. package/dist/design/yaml.js +264 -0
  57. package/dist/design/yaml.js.map +1 -0
  58. package/dist/external.d.ts +61 -0
  59. package/dist/external.d.ts.map +1 -0
  60. package/dist/external.js +426 -0
  61. package/dist/external.js.map +1 -0
  62. package/dist/guide.d.ts +17 -0
  63. package/dist/guide.d.ts.map +1 -0
  64. package/dist/guide.js +219 -0
  65. package/dist/guide.js.map +1 -0
  66. package/dist/index.d.ts +2 -0
  67. package/dist/index.d.ts.map +1 -0
  68. package/dist/index.js +7 -0
  69. package/dist/index.js.map +1 -0
  70. package/dist/install-external.d.ts +3 -0
  71. package/dist/install-external.d.ts.map +1 -0
  72. package/dist/install-external.js +37 -0
  73. package/dist/install-external.js.map +1 -0
  74. package/dist/library-install.d.ts +39 -0
  75. package/dist/library-install.d.ts.map +1 -0
  76. package/dist/library-install.js +663 -0
  77. package/dist/library-install.js.map +1 -0
  78. package/dist/orchestrator/boot.d.ts +3 -0
  79. package/dist/orchestrator/boot.d.ts.map +1 -0
  80. package/dist/orchestrator/boot.js +515 -0
  81. package/dist/orchestrator/boot.js.map +1 -0
  82. package/dist/orchestrator/cli.d.ts +37 -0
  83. package/dist/orchestrator/cli.d.ts.map +1 -0
  84. package/dist/orchestrator/cli.js +563 -0
  85. package/dist/orchestrator/cli.js.map +1 -0
  86. package/dist/orchestrator/commands.d.ts +46 -0
  87. package/dist/orchestrator/commands.d.ts.map +1 -0
  88. package/dist/orchestrator/commands.js +752 -0
  89. package/dist/orchestrator/commands.js.map +1 -0
  90. package/dist/orchestrator/compaction.d.ts +21 -0
  91. package/dist/orchestrator/compaction.d.ts.map +1 -0
  92. package/dist/orchestrator/compaction.js +93 -0
  93. package/dist/orchestrator/compaction.js.map +1 -0
  94. package/dist/orchestrator/drift.d.ts +11 -0
  95. package/dist/orchestrator/drift.d.ts.map +1 -0
  96. package/dist/orchestrator/drift.js +181 -0
  97. package/dist/orchestrator/drift.js.map +1 -0
  98. package/dist/orchestrator/errors.d.ts +52 -0
  99. package/dist/orchestrator/errors.d.ts.map +1 -0
  100. package/dist/orchestrator/errors.js +96 -0
  101. package/dist/orchestrator/errors.js.map +1 -0
  102. package/dist/orchestrator/frontmatter.d.ts +6 -0
  103. package/dist/orchestrator/frontmatter.d.ts.map +1 -0
  104. package/dist/orchestrator/frontmatter.js +50 -0
  105. package/dist/orchestrator/frontmatter.js.map +1 -0
  106. package/dist/orchestrator/fsx.d.ts +45 -0
  107. package/dist/orchestrator/fsx.d.ts.map +1 -0
  108. package/dist/orchestrator/fsx.js +295 -0
  109. package/dist/orchestrator/fsx.js.map +1 -0
  110. package/dist/orchestrator/handoff.d.ts +8 -0
  111. package/dist/orchestrator/handoff.d.ts.map +1 -0
  112. package/dist/orchestrator/handoff.js +246 -0
  113. package/dist/orchestrator/handoff.js.map +1 -0
  114. package/dist/orchestrator/hash.d.ts +10 -0
  115. package/dist/orchestrator/hash.d.ts.map +1 -0
  116. package/dist/orchestrator/hash.js +65 -0
  117. package/dist/orchestrator/hash.js.map +1 -0
  118. package/dist/orchestrator/journal.d.ts +35 -0
  119. package/dist/orchestrator/journal.d.ts.map +1 -0
  120. package/dist/orchestrator/journal.js +163 -0
  121. package/dist/orchestrator/journal.js.map +1 -0
  122. package/dist/orchestrator/lease.d.ts +31 -0
  123. package/dist/orchestrator/lease.d.ts.map +1 -0
  124. package/dist/orchestrator/lease.js +175 -0
  125. package/dist/orchestrator/lease.js.map +1 -0
  126. package/dist/orchestrator/plan.d.ts +27 -0
  127. package/dist/orchestrator/plan.d.ts.map +1 -0
  128. package/dist/orchestrator/plan.js +240 -0
  129. package/dist/orchestrator/plan.js.map +1 -0
  130. package/dist/orchestrator/report.d.ts +49 -0
  131. package/dist/orchestrator/report.d.ts.map +1 -0
  132. package/dist/orchestrator/report.js +244 -0
  133. package/dist/orchestrator/report.js.map +1 -0
  134. package/dist/orchestrator/state.d.ts +43 -0
  135. package/dist/orchestrator/state.d.ts.map +1 -0
  136. package/dist/orchestrator/state.js +369 -0
  137. package/dist/orchestrator/state.js.map +1 -0
  138. package/dist/orchestrator/store.d.ts +42 -0
  139. package/dist/orchestrator/store.d.ts.map +1 -0
  140. package/dist/orchestrator/store.js +202 -0
  141. package/dist/orchestrator/store.js.map +1 -0
  142. package/dist/orchestrator/test-hooks.d.ts +5 -0
  143. package/dist/orchestrator/test-hooks.d.ts.map +1 -0
  144. package/dist/orchestrator/test-hooks.js +31 -0
  145. package/dist/orchestrator/test-hooks.js.map +1 -0
  146. package/dist/orchestrator/time.d.ts +11 -0
  147. package/dist/orchestrator/time.d.ts.map +1 -0
  148. package/dist/orchestrator/time.js +38 -0
  149. package/dist/orchestrator/time.js.map +1 -0
  150. package/dist/paths.d.ts +9 -0
  151. package/dist/paths.d.ts.map +1 -0
  152. package/dist/paths.js +42 -0
  153. package/dist/paths.js.map +1 -0
  154. package/dist/pinned-source.d.ts +13 -0
  155. package/dist/pinned-source.d.ts.map +1 -0
  156. package/dist/pinned-source.js +238 -0
  157. package/dist/pinned-source.js.map +1 -0
  158. package/dist/reconcile/cli.d.ts +17 -0
  159. package/dist/reconcile/cli.d.ts.map +1 -0
  160. package/dist/reconcile/cli.js +171 -0
  161. package/dist/reconcile/cli.js.map +1 -0
  162. package/dist/reconcile/detectors.d.ts +29 -0
  163. package/dist/reconcile/detectors.d.ts.map +1 -0
  164. package/dist/reconcile/detectors.js +294 -0
  165. package/dist/reconcile/detectors.js.map +1 -0
  166. package/dist/reconcile/manifest.d.ts +11 -0
  167. package/dist/reconcile/manifest.d.ts.map +1 -0
  168. package/dist/reconcile/manifest.js +118 -0
  169. package/dist/reconcile/manifest.js.map +1 -0
  170. package/dist/reconcile/queue.d.ts +3 -0
  171. package/dist/reconcile/queue.d.ts.map +1 -0
  172. package/dist/reconcile/queue.js +723 -0
  173. package/dist/reconcile/queue.js.map +1 -0
  174. package/dist/reconcile/score.d.ts +19 -0
  175. package/dist/reconcile/score.d.ts.map +1 -0
  176. package/dist/reconcile/score.js +58 -0
  177. package/dist/reconcile/score.js.map +1 -0
  178. package/dist/scripts/check-opencode-config.d.ts +12 -0
  179. package/dist/scripts/check-opencode-config.d.ts.map +1 -0
  180. package/dist/scripts/check-opencode-config.js +216 -0
  181. package/dist/scripts/check-opencode-config.js.map +1 -0
  182. package/dist/scripts/check-pack.d.ts +3 -0
  183. package/dist/scripts/check-pack.d.ts.map +1 -0
  184. package/dist/scripts/check-pack.js +74 -0
  185. package/dist/scripts/check-pack.js.map +1 -0
  186. package/dist/scripts/check-pins.d.ts +9 -0
  187. package/dist/scripts/check-pins.d.ts.map +1 -0
  188. package/dist/scripts/check-pins.js +65 -0
  189. package/dist/scripts/check-pins.js.map +1 -0
  190. package/dist/scripts/check-security.d.ts +3 -0
  191. package/dist/scripts/check-security.d.ts.map +1 -0
  192. package/dist/scripts/check-security.js +47 -0
  193. package/dist/scripts/check-security.js.map +1 -0
  194. package/dist/scripts/check-skills-lock.d.ts +7 -0
  195. package/dist/scripts/check-skills-lock.d.ts.map +1 -0
  196. package/dist/scripts/check-skills-lock.js +36 -0
  197. package/dist/scripts/check-skills-lock.js.map +1 -0
  198. package/dist/scripts/check-skills-sync.d.ts +7 -0
  199. package/dist/scripts/check-skills-sync.d.ts.map +1 -0
  200. package/dist/scripts/check-skills-sync.js +146 -0
  201. package/dist/scripts/check-skills-sync.js.map +1 -0
  202. package/dist/scripts/check-yaml.d.ts +3 -0
  203. package/dist/scripts/check-yaml.d.ts.map +1 -0
  204. package/dist/scripts/check-yaml.js +41 -0
  205. package/dist/scripts/check-yaml.js.map +1 -0
  206. package/dist/scripts/publish-npm.d.ts +3 -0
  207. package/dist/scripts/publish-npm.d.ts.map +1 -0
  208. package/dist/scripts/publish-npm.js +67 -0
  209. package/dist/scripts/publish-npm.js.map +1 -0
  210. package/dist/scripts/release-check.d.ts +3 -0
  211. package/dist/scripts/release-check.d.ts.map +1 -0
  212. package/dist/scripts/release-check.js +97 -0
  213. package/dist/scripts/release-check.js.map +1 -0
  214. package/dist/scripts/support.d.ts +41 -0
  215. package/dist/scripts/support.d.ts.map +1 -0
  216. package/dist/scripts/support.js +78 -0
  217. package/dist/scripts/support.js.map +1 -0
  218. package/dist/targets/claude.d.ts +4 -0
  219. package/dist/targets/claude.d.ts.map +1 -0
  220. package/dist/targets/claude.js +42 -0
  221. package/dist/targets/claude.js.map +1 -0
  222. package/dist/targets/cline.d.ts +4 -0
  223. package/dist/targets/cline.d.ts.map +1 -0
  224. package/dist/targets/cline.js +39 -0
  225. package/dist/targets/cline.js.map +1 -0
  226. package/dist/targets/cursor.d.ts +4 -0
  227. package/dist/targets/cursor.d.ts.map +1 -0
  228. package/dist/targets/cursor.js +40 -0
  229. package/dist/targets/cursor.js.map +1 -0
  230. package/dist/targets/index.d.ts +4 -0
  231. package/dist/targets/index.d.ts.map +1 -0
  232. package/dist/targets/index.js +11 -0
  233. package/dist/targets/index.js.map +1 -0
  234. package/dist/targets/opencode.d.ts +4 -0
  235. package/dist/targets/opencode.d.ts.map +1 -0
  236. package/dist/targets/opencode.js +48 -0
  237. package/dist/targets/opencode.js.map +1 -0
  238. package/dist/targets/windsurf.d.ts +4 -0
  239. package/dist/targets/windsurf.d.ts.map +1 -0
  240. package/dist/targets/windsurf.js +41 -0
  241. package/dist/targets/windsurf.js.map +1 -0
  242. package/dist/types/common.d.ts +193 -0
  243. package/dist/types/common.d.ts.map +1 -0
  244. package/dist/types/common.js +6 -0
  245. package/dist/types/common.js.map +1 -0
  246. package/dist/types/design.d.ts +185 -0
  247. package/dist/types/design.d.ts.map +1 -0
  248. package/dist/types/design.js +3 -0
  249. package/dist/types/design.js.map +1 -0
  250. package/dist/types/guards.d.ts +13 -0
  251. package/dist/types/guards.d.ts.map +1 -0
  252. package/dist/types/guards.js +64 -0
  253. package/dist/types/guards.js.map +1 -0
  254. package/dist/types/handoff.d.ts +29 -0
  255. package/dist/types/handoff.d.ts.map +1 -0
  256. package/dist/types/handoff.js +3 -0
  257. package/dist/types/handoff.js.map +1 -0
  258. package/dist/types/index.d.ts +7 -0
  259. package/dist/types/index.d.ts.map +1 -0
  260. package/dist/types/index.js +11 -0
  261. package/dist/types/index.js.map +1 -0
  262. package/dist/types/orchestrator.d.ts +414 -0
  263. package/dist/types/orchestrator.d.ts.map +1 -0
  264. package/dist/types/orchestrator.js +4 -0
  265. package/dist/types/orchestrator.js.map +1 -0
  266. package/dist/types/reconcile.d.ts +160 -0
  267. package/dist/types/reconcile.d.ts.map +1 -0
  268. package/dist/types/reconcile.js +3 -0
  269. package/dist/types/reconcile.js.map +1 -0
  270. package/docs/RECONCILE.md +505 -0
  271. package/docs/design/_schema.md +506 -0
  272. package/junamis-skills.yml +328 -0
  273. package/library/EXTERNAL.md +35 -0
  274. package/library/HANDOFF.md +93 -0
  275. package/library/RESUME.md +429 -0
  276. package/library/SAFETY.md +83 -0
  277. package/library/agents/context-keeper.md +41 -0
  278. package/library/agents/frontend.md +43 -0
  279. package/library/agents/maintainer.md +44 -0
  280. package/library/agents/nestjs.md +40 -0
  281. package/library/agents/nextjs.md +40 -0
  282. package/library/agents/operator.md +42 -0
  283. package/library/agents/orchestrator.md +313 -0
  284. package/library/agents/researcher.md +40 -0
  285. package/library/agents/reviewer.md +40 -0
  286. package/library/skills/db-migrate/SKILL.md +50 -0
  287. package/library/skills/decision-record/SKILL.md +74 -0
  288. package/library/skills/dependency-upgrade/SKILL.md +57 -0
  289. package/library/skills/deploy-verify/SKILL.md +51 -0
  290. package/library/skills/document/SKILL.md +51 -0
  291. package/library/skills/env-doctor/SKILL.md +65 -0
  292. package/library/skills/frontend/SKILL.md +63 -0
  293. package/library/skills/handoff/SKILL.md +79 -0
  294. package/library/skills/incident-response/SKILL.md +69 -0
  295. package/library/skills/nestjs/SKILL.md +49 -0
  296. package/library/skills/nextjs/SKILL.md +48 -0
  297. package/library/skills/perf-budget/SKILL.md +62 -0
  298. package/library/skills/refactor-safely/SKILL.md +48 -0
  299. package/library/skills/release-prep/SKILL.md +75 -0
  300. package/library/skills/research/SKILL.md +66 -0
  301. package/library/skills/rollback/SKILL.md +49 -0
  302. package/library/skills/route/SKILL.md +107 -0
  303. package/library/skills/route-external/SKILL.md +67 -0
  304. package/library/skills/security-audit/SKILL.md +64 -0
  305. package/library/skills/skill-author/SKILL.md +49 -0
  306. package/opencode.json +5906 -0
  307. package/package.json +88 -4
  308. package/scripts/design-registry.mjs +7 -0
  309. package/scripts/orchestrator-state.mjs +7 -0
  310. package/scripts/reconcile.mjs +7 -0
  311. package/skills-lock.json +197 -0
@@ -0,0 +1,48 @@
1
+ ---
2
+ name: refactor-safely
3
+ version: "1.0.0"
4
+ idempotent: false
5
+ description: Use when the user asks to restructure, rename, extract, or clean up code and explicitly says behavior must not change. Locks current behavior with characterization tests before editing, then changes code in small steps with the tests run after each step. Do not use when behavior is meant to change; that is a feature or a bug fix.
6
+ ---
7
+
8
+ # refactor-safely
9
+
10
+ Change the shape of code without changing what it does. Prove it with tests written before the change.
11
+
12
+ ## Steps
13
+
14
+ 1. **Scope.** Name the files and the goal in one sentence. If the scope spans more than about 10 files, split it and confirm the first slice with the user.
15
+ 2. **Find the behavior.** Read the code. List its public inputs and outputs, side effects, and error paths.
16
+ 3. **Characterize.** Write tests that assert current behavior, including odd behavior. Run them. They must pass on unmodified code. If one fails, stop: the behavior is not understood yet.
17
+ 4. **Refactor in steps.** One transformation per step (rename, extract function, move module). After each step, run the tests and the type check or linter if the project has one.
18
+ 5. **Stop on red.** If a test fails, revert that step, do not patch the test, and report the step that broke it.
19
+ 6. **Confirm.** Run the full test command once at the end. Compare the public API surface with the baseline.
20
+
21
+ ## Gotchas
22
+
23
+ - Do not "fix" the characterization tests to match a refactor. A changed expectation is a behavior change.
24
+ - Do not mix a bug fix into a refactor. Note the bug as a finding and route it to `debug`.
25
+ - Renames across exports break importers outside the repo. Search for usages in the whole repo first.
26
+ - Tests that always pass prove nothing. Break the code on purpose once to confirm the tests catch it.
27
+
28
+ ## Finish
29
+
30
+ ```yaml
31
+ agent: refactor-safely
32
+ job: refactor <scope>
33
+ status: complete | blocked | failed
34
+ artifacts:
35
+ - path: <changed source files>
36
+ kind: updated
37
+ - path: <new characterization test files>
38
+ kind: created
39
+ findings:
40
+ - id: F1
41
+ severity: medium
42
+ summary: unrelated bug found during refactor
43
+ evidence: <file:line>
44
+ decisions_owed: []
45
+ next: test
46
+ ```
47
+
48
+ Use `next: test` when the suite passes. Use `next: debug` if a finding is a real bug the user wants fixed.
@@ -0,0 +1,75 @@
1
+ ---
2
+ name: release-prep
3
+ version: "1.0.0"
4
+ idempotent: false
5
+ description: Use when a set of commits is ready to become a release. Checks the tree is clean, runs the test command, picks the semver bump from the commits, drafts docs/releases/<version>.md from the real commit log, and produces a release candidate. Do not use to tag, push, publish, or deploy; those are user actions.
6
+ ---
7
+
8
+ # release-prep
9
+
10
+ Get a release candidate to the point where a person can ship it with one command, and stop there.
11
+
12
+ ## Steps
13
+
14
+ 1. **Clean tree.** Run `git status`. Stop with `status: blocked` if there are uncommitted changes. Name them.
15
+ 2. **Range.** Find the last tag (`git describe --tags --abbrev=0`). If none, use the first commit and say so.
16
+ 3. **Tests.** Run the project's test command. Stop with `status: failed` if it fails. Record the summary line. If the external `check` skill is installed, run `check review` on the release diff and record its findings. It reads the code and does not edit it.
17
+ 4. **Bump.** Read the commits since the tag.
18
+ - Any breaking change (`!` after type, or `BREAKING CHANGE:` footer): major.
19
+ - Any `feat`: minor.
20
+ - Otherwise, patch.
21
+ - If commits do not follow conventional format, classify by reading the subject. Name the ones you were unsure about.
22
+ 5. **Version.** Update the version field in the manifest (`package.json` or the project's equivalent). Do not create the tag.
23
+ 6. **Notes.** Write `docs/releases/<version>.md`:
24
+
25
+ ```markdown
26
+ # <version> (<YYYY-MM-DD>)
27
+
28
+ ## Breaking
29
+ - <item, with commit short hash>
30
+
31
+ ## Added
32
+ ## Fixed
33
+ ## Other
34
+
35
+ ## Deploy notes
36
+ - Migrations included: yes | no (list files)
37
+ - Env vars added: <names only>
38
+ - Rollback plan: docs/releases/rollback-<version>.md (required if migrations are included)
39
+ ```
40
+
41
+ 7. **Check.** If migrations are included, require the rollback file to exist before the release is ready. Stop with `needs-decision` if it does not.
42
+ 8. **npm publication checklist.** If the package publishes to npmjs, confirm each item and record the result:
43
+ - the version to publish is the bumped `package.json` version, with no real `1.0.0` when a `v1.0.0` GitHub tag already exists;
44
+ - the `CHANGELOG.md` section for that version is complete;
45
+ - the tag name is `v<version>` and the user, not the skill, creates it;
46
+ - `publish.yml` has the npmjs job with `id-token: write`, the `npm-publish` environment, and `npm stage publish`;
47
+ - the npmjs trusted publisher is configured for owner/repo, workflow `publish.yml`, and environment `npm-publish`;
48
+ - the staged version needs a human 2FA approval on npmjs.com after CI stages it.
49
+ 9. **Deprecation plan.** When this release supersedes a bad or placeholder version, write the deprecation command for the user. It must name the reason, the fixed version or range, and the action. Prefer `npm deprecate` over `npm unpublish`; use unpublish only in npm's 72-hour / no-dependents window with explicit user approval. Record the exact command and the target range.
50
+
51
+ ## Gotchas
52
+
53
+ - Do not invent changelog entries. Each line traces to a commit hash.
54
+ - A version bump without a changelog is incomplete. Write both or neither.
55
+ - Never tag or push. Print the exact commands the user should run, and stop. The skill also stops before the user runs `npm publish`, `npm stage publish`, or `npm deprecate`; those are user actions, and the skill never runs a registry mutation.
56
+ - Do not bump a version that is already tagged. Check the tag list first.
57
+
58
+ ## Finish
59
+
60
+ ```yaml
61
+ agent: release-prep
62
+ job: release candidate <version>
63
+ status: complete | blocked | needs-decision | failed
64
+ artifacts:
65
+ - path: docs/releases/<version>.md
66
+ kind: created
67
+ - path: <manifest file>
68
+ kind: updated
69
+ findings: []
70
+ decisions_owed:
71
+ - confirm major bump to <version>?
72
+ next: user
73
+ ```
74
+
75
+ Always `next: user`. The user tags, pushes, and deploys. After deploy they run `deploy-verify`.
@@ -0,0 +1,66 @@
1
+ ---
2
+ name: research
3
+ version: "1.0.0"
4
+ idempotent: true
5
+ description: Use when the user asks for information that is not in this repo: current docs for a library or API, what a version changed, comparing options, checking whether a package or CVE applies, or finding how others solved a problem. Read-only. Searches the web and public registries, cites every claim, and writes a compact summary to docs/research/. Do not use for questions answerable from this repo's code, and do not use to change anything.
6
+ ---
7
+
8
+ # research
9
+
10
+ Answer one question with sources. Say what is verified and what is not.
11
+
12
+ ## Inputs
13
+
14
+ - The question, verbatim.
15
+ - Version or date constraints if the user gave them. If the answer depends on a version and none was given, use the version in the project's lockfile or manifest and say so.
16
+
17
+ ## Steps
18
+
19
+ 1. **Restate the question** in one line. If it has two readings, pick the one the project needs and name the other in the summary.
20
+ 2. **Check the project first.** Read the lockfile or manifest for the version in question. Do not research a version the project does not use.
21
+ 3. **Search.** Prefer, in order: official docs and changelogs, the package registry page, the source repository's release notes, then reputable articles. Use at least two independent sources for any claim that affects a decision.
22
+ 4. **Verify dates.** Record the publish or update date of every source. Mark anything older than the version in use as possibly stale.
23
+ 5. **Summarize.** Answer first, then evidence. Keep the summary under 300 words unless the user asks for depth.
24
+ 6. **Write** `docs/research/<YYYY-MM-DD>-<slug>.md`:
25
+
26
+ ```markdown
27
+ # <Question>
28
+
29
+ Asked: <YYYY-MM-DD> Version context: <what the project uses>
30
+
31
+ ## Answer
32
+ <two to five sentences>
33
+
34
+ ## Evidence
35
+ - <claim> — <source title>, <url>, <date>
36
+
37
+ ## Unverified
38
+ - <anything you could not confirm from a primary source>
39
+
40
+ ## Not checked
41
+ - <what was out of scope or unreachable>
42
+ ```
43
+
44
+ ## Gotchas
45
+
46
+ - Search results are not sources. Open the page and cite what it says.
47
+ - Do not present a blog post as official behavior. Name the source type.
48
+ - Do not send project code, secrets, or env values in a search query. Describe the problem generically.
49
+ - If two sources disagree, report both and the one you trust more, with the reason. Do not average them.
50
+ - Do not install packages to test a claim. If a test would need installing, say so and stop; that is a user decision.
51
+
52
+ ## Finish
53
+
54
+ ```yaml
55
+ agent: research
56
+ job: answer <question>
57
+ status: complete | blocked | failed
58
+ artifacts:
59
+ - path: docs/research/<YYYY-MM-DD>-<slug>.md
60
+ kind: created
61
+ findings: []
62
+ decisions_owed: []
63
+ next: orchestrator
64
+ ```
65
+
66
+ Use `status: blocked` when no reliable source could be reached. Use `next: user` when the answer depends on a choice only the user can make, and list that choice in `decisions_owed`.
@@ -0,0 +1,49 @@
1
+ ---
2
+ name: rollback
3
+ version: "1.0.0"
4
+ idempotent: false
5
+ description: Use to return a deployed release to the previous version. Reads the rollback plan written at release time, lists each step, and runs them only after the user explicitly confirms in this session. Verifies the result afterward. Do not use without a rollback plan; write one with release-prep first, or stop.
6
+ ---
7
+
8
+ # rollback
9
+
10
+ Restore the last good state, with a confirmed plan and a verified result.
11
+
12
+ ## Inputs
13
+
14
+ - Version to roll back from, and the target version to restore.
15
+ - `docs/releases/rollback-<version>.md`. If it is missing, stop with `status: blocked` and route to `release-prep`.
16
+
17
+ ## Steps
18
+
19
+ 1. **Read the plan.** Show the user the steps from the rollback file, in order, and the data-loss note if one exists.
20
+ 2. **Ask.** Require the user to reply with an explicit confirmation naming the version (for example "roll back 2.4.1"). A general "yes" is not enough. Stop with `status: needs-decision` until you have it.
21
+ 3. **Check state.** Confirm the target version still exists (tag or artifact) and the current deploy is the version named.
22
+ 4. **Execute.** Run the steps in order, only after the confirmation in step 2. Each step that deploys, deletes, or changes git history is a gated command: name it to the user before running it (see `~/.config/junamis/skills/SAFETY.md`). Stop at the first failure. Record each step's output.
23
+ 5. **Migrations.** If the plan reverses a migration, run it only if the plan marks it safe. Otherwise stop and report. Code rollback does not undo schema changes.
24
+ 6. **Verify.** Run `deploy-verify` against the same base URL. The rollback is not done until it passes.
25
+ 7. **Record.** Write `docs/releases/rollback-<version>.md` with the steps run, their outputs, and the verification result.
26
+
27
+ ## Gotchas
28
+
29
+ - A code rollback on a schema that has moved forward can break the old code. Check the expand/contract state first.
30
+ - Rolling back a release does not restore data written after it deployed. Say so in the record.
31
+ - Never force-push or rewrite history to roll back. Redeploy the older artifact.
32
+ - If you are unsure whether a step is reversible, do not run it. Ask.
33
+
34
+ ## Finish
35
+
36
+ ```yaml
37
+ agent: rollback
38
+ job: roll back <version> to <target>
39
+ status: complete | blocked | needs-decision | failed
40
+ artifacts:
41
+ - path: docs/releases/rollback-<version>.md
42
+ kind: created
43
+ findings: []
44
+ decisions_owed:
45
+ - confirm rollback of <version> to <target>?
46
+ next: deploy-verify
47
+ ```
48
+
49
+ Use `next: deploy-verify` after the rollback runs, so the result is checked. Use `next: user` when the rollback is not executed.
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: route
3
+ version: "1.0.0"
4
+ idempotent: true
5
+ description: Use first on every new user request to decide which path it belongs to (feature, bug, refactor, dependency, migration, release, deploy verification, rollback, incident, security, performance, environment, decision, skill, question), routing to internal and external skills alike. Use when the request is not yet classified. When the first skill is external, the orchestrator must run route-external before dispatch. Do not use to do the work itself; it only decides where the work goes.
6
+ ---
7
+
8
+ # route
9
+
10
+ Decide the path for one request and state it in one line. Do no other work.
11
+
12
+ ## Inputs
13
+
14
+ - `<state-root>/resume-report.md`, read in full. It is the first input. If it is missing, return `status: blocked` and tell the orchestrator to run boot.
15
+ - The user request, verbatim.
16
+ - `.junamis/handoff.md` if it exists, for the current goal.
17
+ - `docs/decisions/` titles, if the directory exists.
18
+ - The installed skill inventory: internal skills under `~/.config/junamis/skills/skills/*/SKILL.md` and external skills under the target external skills directory (`~/.agents/skills/*/SKILL.md` for OpenCode, `~/.claude/skills/*/SKILL.md` for Claude Code).
19
+
20
+ ## Paths
21
+
22
+ | Path | Signals | First skill | Owner agent |
23
+ |---|---|---|---|
24
+ | resume | "session restarted", "continue", "pick up", or a resume report with `Status: RESUMING` | the recorded `resolved_skill` | the recorded `owner` |
25
+ | environment | "won't run", "setup", "env", "node version" | `env-doctor` | context-keeper |
26
+ | decision | "we decided", "record this", "going with X" | `decision-record` | context-keeper |
27
+ | tests | "write tests for this change", "cover this with tests", "add a test suite" (after the code exists) | `test` (external) | maintainer |
28
+ | tdd | "build this test-first", "red-green", "TDD this feature" (tests come before the code) | `tdd` (external) | orchestrator |
29
+ | bug | "broken", "error", "wrong output", "fails" | `debug` (external) | orchestrator |
30
+ | refactor | "clean up", "restructure", "no behavior change" | `refactor-safely` | maintainer |
31
+ | dependency | "upgrade X", "bump", "CVE in X" | `dependency-upgrade` | maintainer |
32
+ | migration | "add column", "change schema", "migrate data" | `db-migrate` | maintainer |
33
+ | deploy verification | "check a deployed app", "run post-deploy smoke checks", "verify health after release" | `deploy-verify` | operator |
34
+ | rollback | "roll back", "return to the previous release", "restore the previous deployment" | `rollback` | operator |
35
+ | feature | "add", "build", "new page", "support X" | `architect` then `develop` (external) | orchestrator |
36
+ | nextjs | "next.js", "app router", "server component", "server action" | `nextjs` | nextjs |
37
+ | nestjs | "nestjs", "nest module", "guard", "pipe", "interceptor" | `nestjs` | nestjs |
38
+ | frontend | "ui", "component", "layout", "form", "table", "modal", "shadcn" | `frontend` | frontend |
39
+ | release | "release", "tag", "ship", "deploy" | `release-prep` | operator |
40
+ | publish | "publish to npm", "stage a release", "deprecate a version", "unpublish", "dist-tag", "trusted publisher" | `release-prep` | operator |
41
+ | incident | "prod is down", "users report", "spike", "outage" | `incident-response` | operator |
42
+ | security | "is this safe", "audit", "secrets", "auth review" | `security-audit` | reviewer |
43
+ | performance | "slow", "bundle size", "latency", "web vitals" | `perf-budget` | reviewer |
44
+ | skill | "make a skill", "update a skill", "agent for" | `skill-author` | maintainer |
45
+ | grill | "grill me", "stress-test this plan", "challenge this design", "poke holes" | `grill-me` or `grill-with-docs` (external) | orchestrator |
46
+ | research | "what's the latest", "how do I use X in v3", "compare X and Y", "is CVE-... affecting us", "docs for" | `research` | researcher |
47
+ | question | asks about this repo's code or decisions, no outside info needed, no change requested | none | orchestrator answers directly |
48
+
49
+ External skills (for example `debug`, `architect`, `develop`, `tdd`, `grill-me`) are installed from the upstream manifest, not from this library. The full list and their owners are in `~/.config/junamis/skills/EXTERNAL.md`. If one is not installed, stop and tell the user. Do not substitute. `route-external` is never a path itself; it is the orchestrator's adapter step for an external first skill.
50
+
51
+ ## Resume
52
+
53
+ Read the resume report before scanning the request.
54
+
55
+ - `Status: RESUMING`: start from the cursor task and the recorded `resolved_skill`, `resolution_source`, and `owner`. Do not rescan the user request. Do not resolve capability to skill again when the report says the fingerprint matches.
56
+ - `Status: NEW_RUN`: classify normally with the path table.
57
+ - `Status: COMPLETE`: return `next: none`.
58
+ - `Status: BLOCKED_DRIFT` or `HALT_CORRUPT`: return `status: blocked` with the report path.
59
+
60
+ Use the recorded capability to skill resolution. The plan's resolution is part of its checksum, so the recorded values are the record on resume.
61
+
62
+ ## Work queue
63
+
64
+ Read `<state-root>/work-queue.json` before scanning the request.
65
+
66
+ - `status: blocked_drift`: dispatch nothing. Return `status: blocked` with the drift.
67
+ - `status: no_work`: return `next: none`. If `stalled: true`, report the `summary.blocking_set`.
68
+ - `status: ready`: use `queue[0]`. Never skip past the head.
69
+ - Head `ready: false` with `blocked_by`: do not dispatch; report the blockers.
70
+ - Head `resolution_source: needs_review`: do not dispatch; report the shadow conflict.
71
+ - Head `ready: true`: route to its `capability` and recorded `resolved_skill`.
72
+
73
+ ## Steps
74
+
75
+ 1. **Understand first.** Restate the task in one line: what changes, for whom, and what "done" looks like. Name the expected artifact. If two paths fit, or "done" is unclear, ask one question and wait. Do not guess.
76
+ 2. Read the request. If it names more than one path, pick the one that must finish first. A bug in a release goes to `incident-response` or `debug`, not `release-prep`.
77
+ 3. If an installed external skill matches the request and no internal skill does, that external skill is the path. Say that the orchestrator must run `route-external` before dispatch, so the run ends with a HANDOFF block.
78
+ 4. Write one line: `path: <name> | first: <skill> | reason: <why, under 15 words>`.
79
+ 5. Update `.junamis/handoff.md` only if the goal changed. Otherwise leave it.
80
+
81
+ ## Gotchas
82
+
83
+ - "Fix" is a bug, a refactor, or a dependency bump. Check which before routing.
84
+ - "Deploy" usually means `release-prep` then a user-run deploy. It is never a direct production action from this library.
85
+ - A publish, stage, deprecate, unpublish, or dist-tag request is the `release` path. The operator prepares the release and the user runs every registry mutation. The agent never runs `npm publish`, `npm stage publish`, `npm deprecate`, `npm unpublish`, or `npm dist-tag`; those are user actions.
86
+ - Do not route to a skill because its name matches a word. Route by what must change.
87
+ - If the user explicitly names a skill, honor it unless it clearly conflicts with the request. Say so if it does.
88
+ - Any request that needs information from outside the repo goes to `research`, even if it is phrased as a question.
89
+ - Any request whose work would run a command in the approval gate (`~/.config/junamis/skills/SAFETY.md`) is routed normally. The gate is applied by the owner agent, not by routing.
90
+ - Do not ignore external skills. An installed external skill that fits is a valid path even when the table has no row for it.
91
+ - `route-external` is the orchestrator's adapter step, not a user path. Route to the external skill itself and let the orchestrator adapt it.
92
+
93
+ ## Finish
94
+
95
+ ```yaml
96
+ agent: route
97
+ job: classify request
98
+ status: complete
99
+ artifacts: []
100
+ findings: []
101
+ decisions_owed: []
102
+ next: <first skill from the table>
103
+ ```
104
+
105
+ If the request is a question, `next: none`. If it is ambiguous, `status: needs-decision` with the question in `decisions_owed`.
106
+
107
+ The `next` is the recorded skill on resume, or the normal first skill on a new run.
@@ -0,0 +1,67 @@
1
+ ---
2
+ name: route-external
3
+ version: "1.0.0"
4
+ idempotent: true
5
+ description: Use when the orchestrator is about to dispatch an external skill and that skill must report back in this project's HANDOFF format. Reads the installed external SKILL.md, maps its done, gates, and failure modes to our statuses, and writes a reusable adapter under .junamis/adapters/. Do not use to edit, copy, or rewrite upstream skill content, and do not use for internal library skills.
6
+ ---
7
+
8
+ # route-external
9
+
10
+ You are the orchestrator's adapter maker. You take one installed external skill and give it this project's reporting contract without changing the upstream skill.
11
+
12
+ ## Inputs
13
+
14
+ - The external skill name and its installed `SKILL.md` path.
15
+ - The user request, verbatim.
16
+ - The matching row in `library/SAFETY.md` and entry in `skills-lock.json`.
17
+ - The HANDOFF contract in `~/.config/junamis/skills/HANDOFF.md`.
18
+
19
+ ## Steps
20
+
21
+ 1. **Locate.** Find `<name>/SKILL.md` under `~/.agents/skills/` (OpenCode) or `~/.claude/skills/` (Claude Code). If it is missing, stop with `status: blocked` and name it. Do not install it yourself.
22
+ 2. **Read only.** Read the external `SKILL.md` and any file it says is required. Do not edit it and do not copy its body into the adapter. Quote at most the short trigger or done line you need.
23
+ 3. **Extract.** Record in your own words:
24
+ - its definition of done and the evidence it produces;
25
+ - the artifacts it writes;
26
+ - the commands it runs, and which ones are on the `SAFETY.md` gate;
27
+ - its declared `idempotent: true | false`, if its frontmatter has one;
28
+ - the questions it tends to ask and the failures it can report.
29
+ 4. **Map status.**
30
+ - its done, with evidence present -> `complete`
31
+ - a question only the user can answer -> `needs-decision`
32
+ - a missing tool, dependency, install, or red baseline -> `blocked`
33
+ - it ran and did not reach its done -> `failed`
34
+ 5. **Write the adapter** to `.junamis/adapters/<name>.md` with:
35
+ - upstream source and pinned ref from `skills-lock.json`, and the installed path;
36
+ - the task in the user's words;
37
+ - the short run brief: read the external `SKILL.md`, follow it, stop at the gates, end with one HANDOFF block;
38
+ - the evidence required before `complete`;
39
+ - the gated commands, each marked "ask the user first; not approved by this adapter";
40
+ - the `idempotent: true` or `idempotent: false` value. If the external skill does not declare it, record `false` and add a finding that says the value was not declared. Never guess `true`;
41
+ - a filled HANDOFF template with `agent: <name> (external)`, `status`, `artifacts`, `findings`, `decisions_owed`, `next: orchestrator`.
42
+ 6. **Check the adapter.** No copied upstream prose beyond a short quote. Every `next` resolves to a skill, an agent, `user`, or `none`. Every gated command has an approval line. The adapter records `idempotent: true` or `idempotent: false`.
43
+ 7. **Return.** Report the adapter path. If the external skill already ends in a HANDOFF-compatible block, write a pass-through adapter that says so and keep the same steps.
44
+
45
+ ## Gotchas
46
+
47
+ - The adapter is a wrapper. The external skill stays untouched.
48
+ - Do not put a gate in the adapter as already approved. Approval belongs to the user in the session.
49
+ - Do not adapt an internal library skill. Internal skills already end with a HANDOFF block.
50
+ - Do not adapt a skill that is not installed. Stop and tell the user.
51
+ - An external skill that does not declare `idempotent` is recorded as `false`, never `true`.
52
+ - One adapter per external skill. Reuse and refresh it instead of writing a second one.
53
+ - Never copy external instructions into `library/`; that is upstream content.
54
+
55
+ ## Finish
56
+
57
+ ```yaml
58
+ agent: route-external
59
+ job: adapt external skill <name>
60
+ status: complete | blocked | needs-decision
61
+ artifacts:
62
+ - path: .junamis/adapters/<name>.md
63
+ kind: created | updated
64
+ findings: []
65
+ decisions_owed: []
66
+ next: <the adapted external skill>
67
+ ```
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: security-audit
3
+ version: "1.0.0"
4
+ idempotent: true
5
+ description: Use to review a diff, a branch, or the whole repo for security problems: committed secrets, vulnerable dependencies, missing authorization on endpoints, unsafe input handling, and risky configuration. Read-only. Writes findings to docs/reviews/security-<date>.md, worst first. Do not use to fix code or to test a live system with attack traffic.
6
+ ---
7
+
8
+ # security-audit
9
+
10
+ Find security defects and prove each one with a file and line. Change no code.
11
+
12
+ ## Scope
13
+
14
+ Ask which scope if not given: `diff <base>..<head>`, a path, or the whole repo. Default to the diff against the default branch.
15
+
16
+ ## Checks
17
+
18
+ 1. **Secrets.** Scan the scope for high-entropy strings, private key headers, and common token prefixes. Scan git history of the scope too if the user asks. Report the location, never the value.
19
+ 2. **Dependencies.** Run the project's audit command (`pnpm audit`, `npm audit`, or equivalent) and record advisories by severity. Do not install fixes.
20
+ 3. **Authorization.** For each route or handler in scope, confirm an authentication check and an ownership check where data is per-user. Flag any handler with neither.
21
+ 4. **Input.** Flag string-built SQL, shell commands with interpolated input, `eval`, unsafe deserialization, and HTML rendered from user input without escaping.
22
+ 5. **Config.** Flag `CORS *` with credentials, debug flags enabled by default, cookies without `HttpOnly`, `Secure`, or `SameSite`, and TLS verification disabled.
23
+ 6. **Logging.** Flag logs that include passwords, tokens, or full request bodies from auth routes.
24
+
25
+ ## Output
26
+
27
+ `docs/reviews/security-<YYYY-MM-DD>.md`, one section per finding:
28
+
29
+ ```markdown
30
+ ## [critical] <title>
31
+ Where: <file:line>
32
+ Why it matters: <one sentence>
33
+ Evidence: <the line or command output, with secrets redacted>
34
+ Suggested fix: <one sentence, not applied>
35
+ ```
36
+
37
+ End the file with counts by severity.
38
+
39
+ ## Gotchas
40
+
41
+ - A finding without a file and line is not a finding. Drop it or mark it unverified.
42
+ - Do not mark something "safe" because a framework usually handles it. Confirm in this code.
43
+ - Do not print a secret to prove it exists. Print its file, line, and type.
44
+ - Do not run exploits or send attack payloads at any running service.
45
+
46
+ ## Finish
47
+
48
+ ```yaml
49
+ agent: security-audit
50
+ job: security review of <scope>
51
+ status: complete | failed
52
+ artifacts:
53
+ - path: docs/reviews/security-<YYYY-MM-DD>.md
54
+ kind: created
55
+ findings:
56
+ - id: F1
57
+ severity: critical
58
+ summary: <title>
59
+ evidence: <file:line>
60
+ decisions_owed: []
61
+ next: user
62
+ ```
63
+
64
+ List at most five findings in the handoff block. The full list is in the file. Use `next: maintainer` only if the user asks for fixes.
@@ -0,0 +1,49 @@
1
+ ---
2
+ name: skill-author
3
+ version: "1.0.0"
4
+ idempotent: false
5
+ description: Use to create or update a skill inside library/skills/ so it meets the Agent Skills format, has a routing-rule description, and triggers on the right prompts. Checks for overlap with existing library skills first and runs the library test. Do not use to edit external skills from the upstream manifest; those are not ours to change.
6
+ ---
7
+
8
+ # skill-author
9
+
10
+ Write one skill, in the library, that a fresh agent can run without asking questions.
11
+
12
+ ## Rules the skill must meet
13
+
14
+ - Folder name, `name` field, and parent folder are the same, lowercase, hyphenated.
15
+ - `description` says when to use it and when not to, in one line. Under 1024 characters.
16
+ - Body under 500 lines. Put long reference material in `references/` and say when to load each file.
17
+ - Ends with a `Finish` section containing the HANDOFF block from `~/.config/junamis/skills/HANDOFF.md`.
18
+ - Every `next` value names a skill, an agent, `user`, or `none`.
19
+ - Says what it does not do.
20
+
21
+ ## Steps
22
+
23
+ 1. **Overlap check.** List `library/skills/`. If an existing skill covers the same trigger, stop and propose extending it instead.
24
+ 2. **Trigger check.** Write five prompts that should trigger the skill and five that should not. Confirm each negative belongs to another skill or to none. Put the prompts in the reply, not in a file.
25
+ 3. **Draft.** Write `library/skills/<name>/SKILL.md` with these sections: frontmatter, inputs, steps, gotchas, finish.
26
+ 4. **Assign.** Add the skill to exactly one agent's `skills:` list in `library/agents/`. `route-external` is owned only by the orchestrator. If no agent fits, propose one. Do not create an agent without asking.
27
+ 5. **Test.** Run `pnpm test`. A new skill also needs a row in `SECURITY.md`, an updated `OwnedSkills` count in `junamis-skills.yml`, and the expected count in `test/library.test.js`. Fix every failure before reporting done.
28
+
29
+ ## Gotchas
30
+
31
+ - A description that summarizes ("handles databases") never triggers. Describe the situation the user is in.
32
+ - Do not explain what the agent already knows. Keep what is specific to this project.
33
+ - A skill that does two jobs should be two skills. Split on context boundary.
34
+ - Do not put external skill content into the library. Write original instructions.
35
+
36
+ ## Finish
37
+
38
+ ```yaml
39
+ agent: skill-author
40
+ job: create or update <name>
41
+ status: complete | blocked | needs-decision
42
+ artifacts:
43
+ - path: library/skills/<name>/SKILL.md
44
+ kind: created | updated
45
+ findings: []
46
+ decisions_owed:
47
+ - which agent owns <name>?
48
+ next: none
49
+ ```