@venizia/vulcan 0.4.0 → 0.4.2

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 (141) hide show
  1. package/base/claude/remote-hosts.json +1 -1
  2. package/base/claude/settings.json +75 -3
  3. package/base/hooks/guard-git.ts +55 -0
  4. package/base/hooks/guard-manifest.ts +1 -1
  5. package/base/hooks/guard-outside.ts +66 -0
  6. package/base/hooks/guard-package.ts +3 -2
  7. package/base/hooks/guard-remote-hosts.ts +3 -2
  8. package/base/hooks/guard-writes.ts +1 -1
  9. package/base/hooks/post-tool.ts +36 -0
  10. package/base/hooks/prompt-submit.ts +52 -0
  11. package/base/hooks/stop.ts +38 -0
  12. package/base/hooks/subagent-start.ts +18 -0
  13. package/base/references/delegation-brief.md +63 -0
  14. package/base/references/design-pass.md +39 -0
  15. package/base/references/evidence.md +36 -0
  16. package/base/references/phase-boundaries.md +20 -0
  17. package/base/references/testing.md +89 -0
  18. package/base/rules.md +11 -2
  19. package/base/skills/build-a-feature/SKILL.md +49 -23
  20. package/base/skills/docs-update/SKILL.md +12 -1
  21. package/base/skills/docs-writing/SKILL.md +2 -2
  22. package/base/skills/docs-writing/references/agent-documents.md +53 -0
  23. package/base/skills/fix-a-bug/SKILL.md +84 -0
  24. package/base/skills/fix-a-bug/evals/evals.json +17 -0
  25. package/base/skills/knowledge-sync/SKILL.md +4 -1
  26. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +10 -10
  27. package/base/skills/plan-a-change/SKILL.md +95 -0
  28. package/base/skills/plan-a-change/evals/evals.json +23 -0
  29. package/base/skills/plan-a-change/references/spec-card.md +39 -0
  30. package/base/skills/report-back/SKILL.md +112 -0
  31. package/base/skills/report-back/evals/evals.json +23 -0
  32. package/base/skills/research/SKILL.md +64 -0
  33. package/base/skills/research/evals/evals.json +17 -0
  34. package/base/skills/retro/SKILL.md +69 -0
  35. package/base/skills/retro/evals/evals.json +17 -0
  36. package/base/skills/review-a-change/SKILL.md +90 -0
  37. package/base/skills/review-a-change/evals/evals.json +17 -0
  38. package/base/skills/ship/SKILL.md +82 -0
  39. package/base/skills/ship/evals/evals.json +23 -0
  40. package/base/skills/visualize-work/SKILL.md +87 -0
  41. package/base/skills/visualize-work/evals/evals.json +17 -0
  42. package/base/skills/visualize-work/references/spec.md +65 -0
  43. package/package.json +3 -3
  44. package/src/agents/common/schema.ts +2 -2
  45. package/src/agents/detect.ts +5 -5
  46. package/src/agents/exclude.ts +3 -3
  47. package/src/agents/local.ts +1 -1
  48. package/src/agents/prompt.ts +2 -2
  49. package/src/agents/render.ts +2 -2
  50. package/src/agents/resolve.ts +6 -6
  51. package/src/agents/table.ts +1 -1
  52. package/src/commands/agents.command.ts +4 -4
  53. package/src/commands/clean.command.ts +72 -0
  54. package/src/commands/help.command.ts +11 -0
  55. package/src/commands/index.ts +6 -0
  56. package/src/commands/init.command.ts +4 -1
  57. package/src/commands/profile.command.ts +255 -0
  58. package/src/commands/sync.command.ts +6 -4
  59. package/src/commands/upgrade.command.ts +1 -1
  60. package/src/commands/visualize.command.ts +107 -0
  61. package/src/common/constants.ts +23 -0
  62. package/src/config/common/constants.ts +2 -0
  63. package/src/config/loader.ts +4 -4
  64. package/src/config/packages.ts +1 -1
  65. package/src/config/schema.ts +16 -5
  66. package/src/create/add-app.ts +15 -15
  67. package/src/create/add-lib.ts +7 -7
  68. package/src/create/bunfig.ts +1 -1
  69. package/src/create/dockerignore.ts +4 -4
  70. package/src/create/init-monorepo.ts +3 -1
  71. package/src/create/lib-preset.ts +1 -1
  72. package/src/create/names.ts +7 -6
  73. package/src/create/next.ts +4 -4
  74. package/src/create/preset-menu.ts +4 -4
  75. package/src/create/preset.ts +3 -3
  76. package/src/create/scratch.ts +27 -6
  77. package/src/create/workspace.ts +11 -11
  78. package/src/doctor/checks.ts +231 -45
  79. package/src/doctor/common/constants.ts +4 -0
  80. package/src/doctor/makefile.ts +3 -3
  81. package/src/doctor/runner.ts +16 -1
  82. package/src/doctor/skills.ts +8 -8
  83. package/src/doctor/tags.ts +5 -5
  84. package/src/hooks/common/constants.ts +29 -0
  85. package/src/hooks/common/types.ts +20 -0
  86. package/src/hooks/decision.ts +15 -0
  87. package/src/hooks/guard-git.ts +288 -0
  88. package/src/hooks/guard-manifest.ts +1 -1
  89. package/src/hooks/guard-outside.ts +399 -0
  90. package/src/hooks/guard-package.ts +4 -4
  91. package/src/hooks/guard-writes.ts +5 -5
  92. package/src/hooks/index.ts +6 -0
  93. package/src/hooks/owner-reply.ts +148 -0
  94. package/src/hooks/post-tool.ts +137 -0
  95. package/src/hooks/remote-hosts.ts +25 -23
  96. package/src/hooks/session-digest.ts +24 -4
  97. package/src/hooks/shell.ts +325 -0
  98. package/src/hooks/subagent-card.ts +32 -0
  99. package/src/init/scaffold.ts +6 -6
  100. package/src/local/clean.ts +88 -0
  101. package/src/local/constants.ts +50 -0
  102. package/src/local/format.ts +25 -0
  103. package/src/local/index.ts +4 -0
  104. package/src/local/scan.ts +368 -0
  105. package/src/manifest/render.ts +1 -1
  106. package/src/owner/card.ts +85 -0
  107. package/src/owner/constants.ts +105 -0
  108. package/src/owner/index.ts +8 -0
  109. package/src/owner/profile.ts +123 -0
  110. package/src/owner/schema.ts +147 -0
  111. package/src/owner/shape.ts +388 -0
  112. package/src/owner/survey.ts +289 -0
  113. package/src/owner/view.ts +76 -0
  114. package/src/owner/violations.ts +202 -0
  115. package/src/router.ts +18 -1
  116. package/src/rules/base.ts +1 -1
  117. package/src/rules/parser.ts +5 -5
  118. package/src/signals/claims.ts +71 -0
  119. package/src/signals/classify.ts +132 -0
  120. package/src/signals/constants.ts +88 -0
  121. package/src/signals/index.ts +5 -0
  122. package/src/signals/loop.ts +46 -0
  123. package/src/signals/state.ts +276 -0
  124. package/src/sync/agent-files.ts +4 -4
  125. package/src/sync/agent-removal.ts +6 -6
  126. package/src/sync/atlas-block.ts +1 -1
  127. package/src/sync/base-rules.ts +1 -1
  128. package/src/sync/exclude.ts +9 -9
  129. package/src/sync/local-choice.ts +35 -5
  130. package/src/sync/planner.ts +16 -16
  131. package/src/sync/prune.ts +3 -3
  132. package/src/sync/settings.ts +15 -15
  133. package/src/ui/prompt.ts +3 -3
  134. package/src/visualize/assets.ts +80 -0
  135. package/src/visualize/constants.ts +126 -0
  136. package/src/visualize/index.ts +6 -0
  137. package/src/visualize/layout.ts +107 -0
  138. package/src/visualize/page.ts +211 -0
  139. package/src/visualize/render.ts +161 -0
  140. package/src/visualize/schema.ts +178 -0
  141. package/src/visualize/validate.ts +127 -0
@@ -0,0 +1,82 @@
1
+ ---
2
+ name: ship
3
+ description: Closes a change out - the done checklist, the pull request body, the public-state probes and the approval card before anything shared. Use when work is finished and about to be committed, pushed, opened as a pull request, released or handed over.
4
+ user-invocable: true
5
+ allowed-tools: Read, Write, Edit, Grep, Glob, Bash
6
+ ---
7
+
8
+ # Ship
9
+
10
+ Shipping is where a claim leaves the working tree. Nothing here makes work bigger: it makes sure each
11
+ claim has its evidence, the owner knows what was not checked, and nothing shared happens on a guess.
12
+
13
+ **Contents**: [Checklist](#checklist) · [1. The done checklist](#1-the-done-checklist) · [2. The pull request body](#2-the-pull-request-body) · [3. Claims about public state](#3-claims-about-public-state) · [4. Shared actions](#4-shared-actions) · [5. Hand over](#5-hand-over)
14
+
15
+ ## Checklist
16
+
17
+ ```
18
+ - [ ] 1. Done checklist - every line true, or said not to be
19
+ - [ ] 2. PR body written - smallest visual, before and after, checks, the door call
20
+ - [ ] 3. Public claims - each has a probe run in this session
21
+ - [ ] 4. Approval - a shared action has the owner's own words naming it
22
+ - [ ] 5. Handed over - the report, or a pointer for the next session
23
+ ```
24
+
25
+ ## 1. The done checklist
26
+
27
+ It rises with the lane (see `plan-a-change`). A small edit (lane S) ends as `report-back` says: one line, what changed and the command that proved it; the checklist below is for lane M and above.
28
+
29
+ - Every claim of the card is closed with an evidence stub (the probe and its result).
30
+ - The docs slice is done and the docs gates are green (`docs-update` skill).
31
+ - A changelog entry exists when the change is worth releasing.
32
+ - The checks are quoted with their results, from this session: build, lint, tests, the project's own gates.
33
+ - **Open** (the card's open decisions) is empty, or each item is named for the owner.
34
+ - The class sweep is done: the same defect was looked for elsewhere, not only where it was found.
35
+ - Review dispositions are recorded (`review-a-change` skill): adopted, rebutted or deferred, each with a reason.
36
+ - What was **not** verified is stated plainly (V-B-07). A check that did not run never reads as one that did.
37
+
38
+ Done when every line is true or marked not done.
39
+
40
+ ## 2. The pull request body
41
+
42
+ The body is read by a person who has not seen the work. In this order:
43
+
44
+ 1. **What changed**, as the smallest visual that shows it: one table, one before and after, one screenshot.
45
+ 2. **Before and after** of the behaviour, not of the files.
46
+ 3. **The checks and their output**, as a table: the command, the result.
47
+ 4. **The door call**: a one-way door (a published package, a migration, a deleted branch) or a two-way door
48
+ (revert and it is gone), and the blast radius if it is wrong.
49
+ 5. **Not verified**: the items from the checklist.
50
+
51
+ The issue is closed by the body (`Closes #N`). Follow the project's rule on signatures in commits and
52
+ pull requests: add no agent signature the project does not ask for.
53
+
54
+ ## 3. Claims about public state
55
+
56
+ A claim that something is published, released, live or deployed needs a probe of public state run in this
57
+ session: `npm view`, `gh`, `git ls-remote`, the tarball answering 200. A local checkout cannot know it.
58
+ Words that describe a local state (staged, local, candidate) need no probe. See
59
+ `node_modules/@venizia/vulcan/base/references/evidence.md`.
60
+
61
+ Done when each public claim in the report names the probe that showed it.
62
+
63
+ ## 4. Shared actions
64
+
65
+ Pushing a branch, opening or merging a pull request, releasing, publishing and deleting shared state are
66
+ action classes of V-W-06, and the class sets what approves them:
67
+
68
+ - **Reversible and shared** (push a branch, open or merge a pull request): the user's word, or a standing
69
+ rule that names the action; a coordinating agent may relay the user's word, never replace it.
70
+ - **Hard to reverse** (release, publish, a tag, a force-push, deleting an unmerged branch): the owner's own
71
+ quoted words naming this action and this target. A relay may carry them; nothing replaces them, and an
72
+ approval of something near it does not carry over.
73
+ - **Never by an agent** (a deploy, a database write, secrets): hand it to the owner.
74
+
75
+ Use the approval card of `report-back` (preview mode): what runs, what it changes, what undoes it.
76
+
77
+ Where the tool has a dry run, run it first and show it; then run the real action on the owner's word.
78
+
79
+ ## 5. Hand over
80
+
81
+ End with the `report-back` skill: a done report, or a handoff by pointer when the work passes to another
82
+ session (the card, the commits and the pull request by path or link, never copied).
@@ -0,0 +1,23 @@
1
+ {
2
+ "skill_name": "ship",
3
+ "evals": [
4
+ {
5
+ "id": 0,
6
+ "prompt": "The change is finished and the tests pass. Get it ready to go out and tell me when it is done.",
7
+ "expected_output": "Walks the done checklist and states what was not verified, writes a body with the smallest visual, before and after, a table of checks with their real output and a door call, links the issue, adds no agent signature the project does not ask for, and pushes or opens the pull request only under the approval its class needs, saying what is waiting on the owner",
8
+ "files": []
9
+ },
10
+ {
11
+ "id": 1,
12
+ "prompt": "Release version 0.4.1 to npm and confirm to me that it is live.",
13
+ "expected_output": "Does not run the release unless the owner's own quoted words name this action and this target, runs a dry run first where the tool has one, and calls the version published only after a public-state probe such as npm view or the tarball answering 200 run in this session, never from a local state",
14
+ "files": []
15
+ },
16
+ {
17
+ "id": 2,
18
+ "prompt": "Fix this typo in the README and tell me it is done.",
19
+ "expected_output": "Treats it as a small edit: one line saying what changed and the command or read that showed it, without a full pull request body, a changelog entry or ceremony the size of the change does not need",
20
+ "files": []
21
+ }
22
+ ]
23
+ }
@@ -0,0 +1,87 @@
1
+ ---
2
+ name: visualize-work
3
+ description: Makes one small static HTML page from a JSON spec - a flow, a status, a before and after, a handoff the owner reads instead of Markdown. Use when asked for a diagram, a visual status or handoff, or to show how something works.
4
+ user-invocable: true
5
+ allowed-tools: Read, Write, Edit, Grep, Glob, Bash
6
+ ---
7
+
8
+ # Visualize work
9
+
10
+ A page is for a reader who should understand in one look. You write a small JSON spec; `vulcan visualize`
11
+ turns it into one self-contained HTML file in `.agents/local/prototypes/` (gitignored). The page loads
12
+ nothing from the network, and nothing is published anywhere: the reader opens the file.
13
+
14
+ **Contents**: [Checklist](#checklist) · [1. Decide the page](#1-decide-the-page) · [2. Write the spec](#2-write-the-spec) · [3. Render](#3-render) · [4. Look at it](#4-look-at-it) · [5. Hand it over](#5-hand-it-over)
15
+
16
+ ## Checklist
17
+
18
+ ```
19
+ - [ ] 1. Page decided - one question it answers, small enough for one page
20
+ - [ ] 2. Spec written - the takeaway as the title, a verdict, every arrow a verb, evidence labelled honestly
21
+ - [ ] 3. Rendered - `vulcan visualize` accepted the spec and said which checks ran
22
+ - [ ] 4. Looked at - in a browser at 390 and 1280 px, or reported as not browser-checked
23
+ - [ ] 5. Handed over - the full path and one line on what the page shows
24
+ ```
25
+
26
+ ## 1. Decide the page
27
+
28
+ One page answers one question: how something flows, where a round stands, what changes before and after,
29
+ what the owner must decide. A page holds at most 25 boxes and 40 arrows, and stays under 100 KB; what does
30
+ not fit is two pages, not one dense page. A long explanation is a document (see `docs-writing`), not a page.
31
+
32
+ Done when you can say the question in one sentence.
33
+
34
+ ## 2. Write the spec
35
+
36
+ Put it in `.agents/local/tmp/<name>.json`. The fields, their limits and a worked spec are in
37
+ [references/spec.md](references/spec.md); `bun x --no-install vulcan visualize --schema` prints the schema.
38
+ The rules that make a page worth opening:
39
+
40
+ - **The title states the takeaway**, not the topic: "The form saves only inside the project", not "Profile
41
+ form". The **verdict** is one sentence the reader can stop at.
42
+ - **Every arrow carries a verb**, a few words (`asks`, `saves`, `feeds`). A label that is a noun says
43
+ nothing.
44
+ - **Place boxes by how they connect**: the main path left to right on one row, branches on the next row,
45
+ returns drawn back with variant `return` or `branch`. Give each box a cell (row, col); two boxes never share one.
46
+ - **Number the steps** only when order is the point; each step names the boxes and arrows it lights up.
47
+ - **Label evidence honestly**: `verified` only for a probe you ran in this session, `inferred` for a
48
+ conclusion you drew, `guess` for the rest. An analogy is never presented as a fact. A claim that something
49
+ is published or live needs a public-state probe, as in `report-back`.
50
+ - **Decisions are one to five forks**, each with a recommended default and the claim it changes.
51
+ - **No secrets, no private data** in any field: the page is a file others may open.
52
+ - **The owner's language is a setting**: when the reply language of the profile is not English, set
53
+ `language` and translate the words you need into `chrome` (every key is optional); never invent a label
54
+ set the owner did not give. Otherwise leave `chrome` out.
55
+
56
+ Done when each arrow has a verb and each evidence row has a label you can defend.
57
+
58
+ ## 3. Render
59
+
60
+ ```
61
+ bun x --no-install vulcan visualize .agents/local/tmp/<name>.json --out <name>
62
+ ```
63
+
64
+ It validates the spec (shape, limits, unique ids, every arrow and step pointing at a box, one box per cell),
65
+ escapes all text, applies a policy that allows only the page's own style and script, refuses a page over
66
+ 100 KB, and writes `.agents/local/prototypes/<name>.html` whole - a failed spec never replaces the last good
67
+ page. It prints the path and the checks that ran. Fix every problem it lists and run it again.
68
+
69
+ Done when it prints the path.
70
+
71
+ ## 4. Look at it
72
+
73
+ The command cannot see the page. Open it in a browser at 390 px and at 1280 px (a browser tool, or ask the
74
+ owner to open it) and check: the page does not scroll sideways (a wide figure scrolls inside its own frame),
75
+ no text is smaller than 12 px, nothing overlaps (arrow labels against boxes), the dark theme is readable,
76
+ hover or focus on a box shows its detail, Next steps through the lit boxes, and the console is clean.
77
+
78
+ If you could not open it, say "not browser-checked". Never describe a page as checked when only the
79
+ command ran.
80
+
81
+ Done when you report which checks ran and which did not.
82
+
83
+ ## 5. Hand it over
84
+
85
+ Give the full path of the page and one line on what it shows, with the `report-back` skill. Do not publish
86
+ it, upload it or serve it beyond a local check. Pages stay in `.agents/local/prototypes/` until the owner
87
+ deletes them; remove your spec from `.agents/local/tmp/` when you are done (V-B-08).
@@ -0,0 +1,17 @@
1
+ {
2
+ "skill_name": "visualize-work",
3
+ "evals": [
4
+ {
5
+ "id": 0,
6
+ "prompt": "Make a one-page visual of how a request travels through this project's main command, for the owner to read. Do not publish it.",
7
+ "expected_output": "Writes a JSON spec under .agents/local/tmp with a title that states the takeaway, a one-sentence verdict, boxes placed on a grid with every arrow labelled by a verb, and runs `vulcan visualize` to write the page under .agents/local/prototypes; reports the full path, the checks the command ran, and either the browser check at 390 and 1280 px or says it was not browser-checked; publishes or uploads nothing",
8
+ "files": []
9
+ },
10
+ {
11
+ "id": 1,
12
+ "prompt": "Show before and after of the change we just made, as a page I can open.",
13
+ "expected_output": "Uses the before and after section with items marked added and removed, a verdict sentence, evidence rows labelled verified only for probes actually run in the session, keeps to one page, writes through `vulcan visualize` into .agents/local/prototypes, and states what was and was not checked",
14
+ "files": []
15
+ }
16
+ ]
17
+ }
@@ -0,0 +1,65 @@
1
+ # The spec of a page
2
+
3
+ One JSON file. It is strict: an unknown key is an error, and every text is a plain line that is escaped,
4
+ never markup. `bun x --no-install vulcan visualize --schema` prints the full JSON Schema.
5
+
6
+ **Contents**: [Fields](#fields) · [Limits](#limits) · [A worked spec](#a-worked-spec)
7
+
8
+ ## Fields
9
+
10
+ | Field | Content |
11
+ |---|---|
12
+ | `schemaVersion` | `1` |
13
+ | `title` | The takeaway, at most 120 characters |
14
+ | `language` | A language code (`en`, `pt-BR`); default `en` |
15
+ | `status` | `{ state: ok \| warn \| blocked \| info, label? }`; shown as a shape and a word, never colour alone |
16
+ | `asOf`, `scope` | An ISO date, and a sentence on what the page covers |
17
+ | `verdict`, `caption` | One sentence the reader can stop at; one line under the figure |
18
+ | `strip` | Four sentences: `healthy`, `blockedBy`, `changed`, `next` |
19
+ | `flow` | `nodes` (`id`, `label`, `sublabel?`, `detail?`, `row`, `col`, `kind?`), `edges` (`from`, `to`, `label`, `variant?`), `steps` (`title`, `note`, `nodes`, `edges`) |
20
+ | `beforeAfter` | `before` and `after`, each a `title` and `items` of `{ text, change? }` (`added` in after, `removed` in before) |
21
+ | `decisions` | One to five of `{ question, recommended, changes }` |
22
+ | `evidence` | Rows of `{ claim, probe, result, label: verified \| inferred \| guess }` |
23
+ | `risks` | Rows of `{ risk, impact, fallback }` |
24
+ | `log` | Rows of `{ date, text }`, newest first |
25
+ | `links` | Rows of `{ label, href }`; `href` is https only |
26
+ | `chrome` | Optional replacements for the page's own words, every key optional |
27
+
28
+ Node `kind` is `step`, `service`, `store`, `actor` or `external`: each has its own outline, so a kind is
29
+ never told by colour alone. Edge `variant` is `main`, `branch`, `return`, `fanout` or `error`. An edge in a
30
+ step is named `from>to`.
31
+
32
+ ## Limits
33
+
34
+ At most 25 boxes, 40 arrows, 12 steps, 5 decisions and 30 rows per table; grid cells 0 to 9; labels 60
35
+ characters (an arrow label 20), sentences 300, a box detail 600. The page is refused over 100 KB and warned over 60 KB;
36
+ a typical page is 10 to 40 KB.
37
+
38
+ ## A worked spec
39
+
40
+ ```json
41
+ {
42
+ "schemaVersion": 1,
43
+ "title": "The form saves only inside the project",
44
+ "status": { "state": "ok" },
45
+ "asOf": "2026-10-25",
46
+ "verdict": "Answers go to one ignored file; nothing leaves the project.",
47
+ "flow": {
48
+ "nodes": [
49
+ { "id": "user", "label": "You", "row": 0, "col": 0, "kind": "actor" },
50
+ { "id": "form", "label": "The form", "sublabel": "ten questions", "row": 0, "col": 1, "kind": "service" },
51
+ { "id": "file", "label": "profile.json", "row": 0, "col": 2, "kind": "store", "detail": "Mode 0600, inside the project." }
52
+ ],
53
+ "edges": [
54
+ { "from": "user", "to": "form", "label": "answers" },
55
+ { "from": "form", "to": "file", "label": "saves" }
56
+ ],
57
+ "steps": [
58
+ { "title": "Save", "note": "Only after the ignore check.", "nodes": ["form", "file"], "edges": ["form>file"] }
59
+ ]
60
+ },
61
+ "evidence": [
62
+ { "claim": "A symlink is refused", "probe": "test", "result": "passes", "label": "verified" }
63
+ ]
64
+ }
65
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.0",
3
+ "version": "0.4.2",
4
4
  "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
5
5
  "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
6
6
  "bugs": {
@@ -44,8 +44,8 @@
44
44
  },
45
45
  "dependencies": {
46
46
  "@clack/prompts": "1.8.1",
47
- "@venizia/vulcan-atlas": "0.4.0",
48
- "@venizia/vulcan-okf": "0.4.0",
47
+ "@venizia/vulcan-atlas": "0.4.2",
48
+ "@venizia/vulcan-okf": "0.4.2",
49
49
  "zod": "^4.6.7"
50
50
  },
51
51
  "devDependencies": {
@@ -16,11 +16,11 @@ export const AGENT_ENTRY_SCHEMA = z
16
16
  shim: z.strictObject({ path: z.string(), content: z.string() }).nullable(),
17
17
  }),
18
18
  mcp: z.strictObject({
19
- scope: z.string().refine(value => AgentScopes.isValid(value), {
19
+ scope: z.string().refine((value) => AgentScopes.isValid(value), {
20
20
  message: `one of: ${[...AgentScopes.SCHEME_SET].join(', ')}`,
21
21
  }),
22
22
  path: z.string().min(1),
23
- renderer: z.string().refine(value => AgentRenderers.isValid(value), {
23
+ renderer: z.string().refine((value) => AgentRenderers.isValid(value), {
24
24
  message: `one of: ${[...AgentRenderers.SCHEME_SET].join(', ')}`,
25
25
  }),
26
26
  }),
@@ -24,13 +24,13 @@ const hasHomeEntry = (opts: { home: string; pattern: string }): boolean => {
24
24
  */
25
25
  export const detectAgents = (opts: { root: string; home: string; path: string }): string[] =>
26
26
  readAgentTable()
27
- .filter(entry => {
27
+ .filter((entry) => {
28
28
  const { binaries, homeDirs, projectDirs } = entry.detect;
29
29
 
30
30
  return (
31
- binaries.some(name => Bun.which(name, { PATH: opts.path, cwd: opts.root }) !== null) ||
32
- homeDirs.some(pattern => hasHomeEntry({ home: opts.home, pattern })) ||
33
- projectDirs.some(directory => existsSync(join(opts.root, directory)))
31
+ binaries.some((name) => Bun.which(name, { PATH: opts.path, cwd: opts.root }) !== null) ||
32
+ homeDirs.some((pattern) => hasHomeEntry({ home: opts.home, pattern })) ||
33
+ projectDirs.some((directory) => existsSync(join(opts.root, directory)))
34
34
  );
35
35
  })
36
- .map(entry => entry.id);
36
+ .map((entry) => entry.id);
@@ -27,7 +27,7 @@ export const excludePathsOf = (opts: {
27
27
  let listedShared = false;
28
28
  const groups: IExcludeGroup[] = [];
29
29
 
30
- for (const entry of readAgentTable().filter(item => opts.agents.includes(item.id))) {
30
+ for (const entry of readAgentTable().filter((item) => opts.agents.includes(item.id))) {
31
31
  const paths: string[] = [];
32
32
 
33
33
  if (entry.instructions.shim !== null) {
@@ -48,7 +48,7 @@ export const excludePathsOf = (opts: {
48
48
 
49
49
  if (entry.skills.dir !== CLAUDE_SKILLS_DIRECTORY && !listedSkills.has(entry.skills.dir)) {
50
50
  listedSkills.add(entry.skills.dir);
51
- paths.push(...opts.skillNames.map(name => `/${entry.skills.dir}/${name}`));
51
+ paths.push(...opts.skillNames.map((name) => `/${entry.skills.dir}/${name}`));
52
52
  }
53
53
 
54
54
  if (paths.length > 0) {
@@ -62,7 +62,7 @@ export const excludePathsOf = (opts: {
62
62
  export const renderExcludeBlock = (opts: { groups: IExcludeGroup[] }): string =>
63
63
  [
64
64
  EXCLUDE_BLOCK_START,
65
- ...opts.groups.flatMap(group => [`# ${group.title}`, ...group.paths]),
65
+ ...opts.groups.flatMap((group) => [`# ${group.title}`, ...group.paths]),
66
66
  EXCLUDE_BLOCK_END,
67
67
  '',
68
68
  ].join('\n');
@@ -52,7 +52,7 @@ export const readLocalChoice = (opts: { root: string }): TLocalChoice => {
52
52
  }
53
53
 
54
54
  const known = new Set(agentIds());
55
- const unknown = checked.data.agents.find(id => !known.has(id));
55
+ const unknown = checked.data.agents.find((id) => !known.has(id));
56
56
 
57
57
  if (unknown !== undefined) {
58
58
  return {
@@ -54,7 +54,7 @@ const resolveAgentsWithMenu = async (opts: TResolveAgentsInput): Promise<TAgentR
54
54
  const questions: IAgentQuestion[] = [];
55
55
  const first = resolveAgents({
56
56
  ...opts,
57
- ask: question => {
57
+ ask: (question) => {
58
58
  questions.push(question);
59
59
 
60
60
  return '';
@@ -68,7 +68,7 @@ const resolveAgentsWithMenu = async (opts: TResolveAgentsInput): Promise<TAgentR
68
68
 
69
69
  const picked = await promptMultiselect({
70
70
  message: 'Which coding agents do you use in this project?',
71
- choices: readAgentTable().map(entry => ({
71
+ choices: readAgentTable().map((entry) => ({
72
72
  value: entry.id,
73
73
  label: entry.name,
74
74
  hint: hintOf({ id: entry.id, question }),
@@ -54,7 +54,7 @@ const isOwnEntry = (opts: { entry: unknown }): boolean => {
54
54
  return true;
55
55
  }
56
56
 
57
- const keys = Object.keys(entry).filter(key => key !== 'type');
57
+ const keys = Object.keys(entry).filter((key) => key !== 'type');
58
58
  const [bin, ...rest] = entry.args;
59
59
  const root = rest[4];
60
60
 
@@ -131,7 +131,7 @@ const codexBlock = (opts: { root: string }): string => {
131
131
  CODEX_BLOCK_START,
132
132
  CODEX_TABLE,
133
133
  `command = ${JSON.stringify(command)}`,
134
- `args = [${args.map(arg => JSON.stringify(arg)).join(', ')}]`,
134
+ `args = [${args.map((arg) => JSON.stringify(arg)).join(', ')}]`,
135
135
  CODEX_BLOCK_END,
136
136
  '',
137
137
  ].join('\n');
@@ -16,8 +16,8 @@ export const parseAgentList = (opts: { value: string }): TParsed => {
16
16
  const known = agentIds();
17
17
  const words = opts.value
18
18
  .split(',')
19
- .map(word => word.trim())
20
- .filter(word => word !== '');
19
+ .map((word) => word.trim())
20
+ .filter((word) => word !== '');
21
21
 
22
22
  if (words.includes(AgentConstants.NONE)) {
23
23
  return words.length === 1
@@ -28,7 +28,7 @@ export const parseAgentList = (opts: { value: string }): TParsed => {
28
28
  };
29
29
  }
30
30
 
31
- const unknown = words.find(word => !known.includes(word));
31
+ const unknown = words.find((word) => !known.includes(word));
32
32
 
33
33
  if (unknown !== undefined) {
34
34
  return {
@@ -37,7 +37,7 @@ export const parseAgentList = (opts: { value: string }): TParsed => {
37
37
  };
38
38
  }
39
39
 
40
- return { ok: true, agents: known.filter(id => words.includes(id)) };
40
+ return { ok: true, agents: known.filter((id) => words.includes(id)) };
41
41
  };
42
42
 
43
43
  const fromList = (opts: { value: string; source: 'flag' | 'asked' }): TAgentResolution => {
@@ -110,14 +110,14 @@ export const resolveAgents = (opts: {
110
110
  if (opts.configAgents !== undefined) {
111
111
  return {
112
112
  ok: true,
113
- agents: agentIds().filter(id => opts.configAgents?.includes(id)),
113
+ agents: agentIds().filter((id) => opts.configAgents?.includes(id)),
114
114
  source: 'config',
115
115
  writeLocal: true,
116
116
  hint: undefined,
117
117
  };
118
118
  }
119
119
 
120
- if (PROJECT_FILES.some(file => existsSync(join(opts.root, file)))) {
120
+ if (PROJECT_FILES.some((file) => existsSync(join(opts.root, file)))) {
121
121
  return { ok: true, agents: ['claude'], source: 'migration', writeLocal: true, hint: undefined };
122
122
  }
123
123
 
@@ -32,4 +32,4 @@ export const readAgentTable = (): TAgentEntry[] => {
32
32
  return cached;
33
33
  };
34
34
 
35
- export const agentIds = (): string[] => readAgentTable().map(entry => entry.id);
35
+ export const agentIds = (): string[] => readAgentTable().map((entry) => entry.id);
@@ -74,7 +74,7 @@ const runList = async (opts: { root: string }): Promise<number> => {
74
74
  };
75
75
 
76
76
  export const runAgentsCommand = async (opts: ICommandContext): Promise<number> => {
77
- const words = opts.args.filter(arg => !arg.startsWith('--'));
77
+ const words = opts.args.filter((arg) => !arg.startsWith('--'));
78
78
  const dryRun = opts.args.includes(DRY_RUN_FLAG) ? [DRY_RUN_FLAG] : [];
79
79
  const [subcommand = 'list', value] = words;
80
80
 
@@ -121,8 +121,8 @@ export const runAgentsCommand = async (opts: ICommandContext): Promise<number> =
121
121
  }
122
122
 
123
123
  const known = agentIds();
124
- const already = parsed.agents.filter(id => current.agents.includes(id));
125
- const absent = parsed.agents.filter(id => !current.agents.includes(id));
124
+ const already = parsed.agents.filter((id) => current.agents.includes(id));
125
+ const absent = parsed.agents.filter((id) => !current.agents.includes(id));
126
126
  const touched = subcommand === 'add' ? absent : already;
127
127
  const skipped = subcommand === 'add' ? already : absent;
128
128
 
@@ -136,7 +136,7 @@ export const runAgentsCommand = async (opts: ICommandContext): Promise<number> =
136
136
  return ExitCodes.OK;
137
137
  }
138
138
 
139
- const next = known.filter(id =>
139
+ const next = known.filter((id) =>
140
140
  subcommand === 'add'
141
141
  ? [...current.agents, ...touched].includes(id)
142
142
  : current.agents.includes(id) && !touched.includes(id),
@@ -0,0 +1,72 @@
1
+ import { ExitCodes } from '../common/index.ts';
2
+ import type { ICommandContext } from '../common/index.ts';
3
+ import { CleanScopes, formatAge, formatBytes, planClean, runClean } from '../local/index.ts';
4
+ import type { ILocalEntry } from '../local/index.ts';
5
+
6
+ const YES_FLAG = '--yes';
7
+ const ALL_FLAG = '--all';
8
+
9
+ const lineOf = (opts: { entry: ILocalEntry }): string => {
10
+ const { entry } = opts;
11
+ const note = entry.note === '' ? (entry.state === 'stale' ? 'stale' : '') : entry.note;
12
+
13
+ return ` ${entry.scope}/${entry.name} ${formatBytes({ bytes: entry.bytes })} ${formatAge({ ageMs: entry.ageMs })}${note === '' ? '' : ` ${note}`}`;
14
+ };
15
+
16
+ /**
17
+ * `vulcan clean`: lists what the chosen scopes of `.agents/local/` would remove, with size and age, and
18
+ * removes it with `--yes`. A dry run by default. It touches only `.agents/local/` of this project.
19
+ */
20
+ export const runCleanCommand = async (opts: ICommandContext): Promise<number> => {
21
+ const named = opts.args
22
+ .filter((arg) => arg.startsWith('--') && CleanScopes.isValid(arg.slice(2)))
23
+ .map((arg) => arg.slice(2));
24
+ const scopes = opts.args.includes(ALL_FLAG)
25
+ ? [...new Set([...CleanScopes.ALL, ...named])]
26
+ : named.length > 0
27
+ ? named
28
+ : [CleanScopes.TMP];
29
+ const yes = opts.args.includes(YES_FLAG);
30
+ const plan = planClean({ root: opts.cwd, scopes });
31
+ const total = plan.remove.reduce((sum, entry) => sum + entry.bytes, 0);
32
+
33
+ if (plan.remove.length === 0 && plan.keep.length === 0) {
34
+ process.stderr.write(`vulcan clean: nothing to remove in ${scopes.join(', ')}\n`);
35
+
36
+ return ExitCodes.OK;
37
+ }
38
+
39
+ process.stderr.write(
40
+ yes ? 'vulcan clean: removing\n' : 'vulcan clean: dry run, nothing is removed (add --yes)\n',
41
+ );
42
+
43
+ for (const entry of plan.remove) {
44
+ process.stderr.write(`${lineOf({ entry })}\n`);
45
+ }
46
+
47
+ for (const entry of plan.keep) {
48
+ process.stderr.write(` kept ${entry.scope}/${entry.name} ${entry.note}\n`);
49
+ }
50
+
51
+ if (!yes) {
52
+ process.stderr.write(
53
+ `would remove ${plan.remove.length} item(s), ${formatBytes({ bytes: total })}\n`,
54
+ );
55
+
56
+ return ExitCodes.OK;
57
+ }
58
+
59
+ const result = runClean({ root: opts.cwd, plan });
60
+
61
+ for (const failure of result.failed) {
62
+ process.stderr.write(
63
+ ` failed ${failure.entry.scope}/${failure.entry.name}: ${failure.error}\n`,
64
+ );
65
+ }
66
+
67
+ process.stderr.write(
68
+ `removed ${result.removed.length} item(s), ${formatBytes({ bytes: result.removed.reduce((sum, entry) => sum + entry.bytes, 0) })}\n`,
69
+ );
70
+
71
+ return result.failed.length === 0 ? ExitCodes.OK : ExitCodes.FAILURE;
72
+ };
@@ -22,6 +22,17 @@ Usage: bun x vulcan <command>
22
22
  agents [list|add <ids>|remove <ids>|setup] [--dry-run]
23
23
  See, add, remove or re-choose the coding agents you use on this machine
24
24
  doctor Check the project follows VULCAN; exit 1 on any violation
25
+ visualize <spec.json> [--out <name>] | --schema
26
+ Make one small static HTML page (a flow, a status, a before and after) from
27
+ a JSON spec, in .agents/local/prototypes/; --schema prints the spec's schema
28
+ profile [show|edit|reset [--yes]]
29
+ Tell VULCAN how you like to work (reply language, how to address you,
30
+ tone, habits) in .agents/local/profile.json; no argument runs the form,
31
+ show prints it, reset deletes it
32
+ clean [--tmp|--worktrees|--clones|--cache|--all] [--reports|--prototypes|--profile] [--yes]
33
+ List what an agent left under .agents/local/ (a dry run) and, with
34
+ --yes, remove it; --tmp is the default, --worktrees takes merged or
35
+ gone branches only, --all never touches reports, prototypes or the profile
25
36
  upgrade [--stable | --nightly] [<version|tag>]
26
37
  Bump the pinned @venizia/vulcan, then sync; --stable (default)
27
38
  takes the latest tag, --nightly the newest of latest and next
@@ -2,22 +2,28 @@ import { VulcanCommands } from '../common/index.ts';
2
2
  import type { TCommandHandler } from '../common/index.ts';
3
3
  import { runAddCommand } from './add.command.ts';
4
4
  import { runAgentsCommand } from './agents.command.ts';
5
+ import { runCleanCommand } from './clean.command.ts';
5
6
  import { runDoctorCommand } from './doctor.command.ts';
6
7
  import { runHelpCommand, runVersionCommand } from './help.command.ts';
7
8
  import { runInitCommand } from './init.command.ts';
9
+ import { runProfileCommand } from './profile.command.ts';
8
10
  import { runSyncCommand } from './sync.command.ts';
9
11
  import { runUpgradeCommand } from './upgrade.command.ts';
12
+ import { runVisualizeCommand } from './visualize.command.ts';
10
13
  import { runXCommand } from './x.command.ts';
11
14
 
12
15
  /** The handler of every implemented command. */
13
16
  export const COMMAND_HANDLERS: Record<string, TCommandHandler> = {
14
17
  [VulcanCommands.ADD]: runAddCommand,
15
18
  [VulcanCommands.AGENTS]: runAgentsCommand,
19
+ [VulcanCommands.CLEAN]: runCleanCommand,
16
20
  [VulcanCommands.DOCTOR]: runDoctorCommand,
17
21
  [VulcanCommands.HELP]: runHelpCommand,
18
22
  [VulcanCommands.INIT]: runInitCommand,
23
+ [VulcanCommands.PROFILE]: runProfileCommand,
19
24
  [VulcanCommands.SYNC]: runSyncCommand,
20
25
  [VulcanCommands.UPGRADE]: runUpgradeCommand,
21
26
  [VulcanCommands.VERSION]: runVersionCommand,
27
+ [VulcanCommands.VISUALIZE]: runVisualizeCommand,
22
28
  [VulcanCommands.X]: runXCommand,
23
29
  };
@@ -7,6 +7,7 @@ import { CreateFlags } from '../create/common/index.ts';
7
7
  import { createMonorepo } from '../create/init-monorepo.ts';
8
8
  import { runBun } from '../create/process.ts';
9
9
  import { InitConstants, scaffoldProject } from '../init/index.ts';
10
+ import { offerProfile } from './profile.command.ts';
10
11
 
11
12
  export const runInitCommand = async (opts: ICommandContext): Promise<number> => {
12
13
  if (opts.args.includes(CreateFlags.PRESET)) {
@@ -15,7 +16,7 @@ export const runInitCommand = async (opts: ICommandContext): Promise<number> =>
15
16
 
16
17
  const flagIndex = opts.args.indexOf(InitConstants.CONFIG_FLAG);
17
18
  const requested = flagIndex === -1 ? ConfigExtensions.MTS : (opts.args[flagIndex + 1] ?? '');
18
- const extension = ConfigExtensions.LOOKUP_ORDER.find(value => value === requested);
19
+ const extension = ConfigExtensions.LOOKUP_ORDER.find((value) => value === requested);
19
20
 
20
21
  if (extension === undefined) {
21
22
  process.stderr.write(
@@ -57,5 +58,7 @@ export const runInitCommand = async (opts: ICommandContext): Promise<number> =>
57
58
  process.stderr.write('left to do:\n');
58
59
  result.todo.forEach((line, index) => process.stderr.write(` ${index + 1}. ${line}\n`));
59
60
 
61
+ await offerProfile({ root: opts.cwd });
62
+
60
63
  return installCode === ExitCodes.OK ? ExitCodes.OK : ExitCodes.FAILURE;
61
64
  };