@mthanh/vespercli 1.5.0 → 1.6.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.
- package/README.md +139 -78
- package/assets/CATALOG.md +6 -0
- package/assets/claude/agents/feature-wrap-document.md +112 -9
- package/assets/claude/skills/agent-fundamentals/SKILL.md +14 -0
- package/assets/claude/skills/gitlab-guardrails/SKILL.md +62 -0
- package/assets/claude/vesper-orchestrator.md +3 -0
- package/assets/core/agents/feature-wrap-document.agent.md +20 -11
- package/assets/core/agents/vesper.agent.md +3 -0
- package/assets/core/skills/agent-fundamentals/SKILL.md +14 -0
- package/assets/hooks/pre-commit +17 -1
- package/assets/manifest.json +36 -0
- package/assets/skills/aesthetic/manifest.json +1 -1
- package/assets/skills/ai-multimodal/manifest.json +1 -1
- package/assets/skills/backend-development/manifest.json +1 -1
- package/assets/skills/better-auth/manifest.json +1 -1
- package/assets/skills/chrome-devtools/manifest.json +1 -1
- package/assets/skills/code-review/manifest.json +1 -1
- package/assets/skills/databases/manifest.json +1 -1
- package/assets/skills/debugging/manifest.json +1 -1
- package/assets/skills/devops/manifest.json +1 -1
- package/assets/skills/docs-seeker/manifest.json +1 -1
- package/assets/skills/document-skills/manifest.json +1 -1
- package/assets/skills/frontend-design/manifest.json +1 -1
- package/assets/skills/gitlab-guardrails/SKILL.md +62 -0
- package/assets/skills/gitlab-guardrails/manifest.json +8 -0
- package/assets/skills/google-adk-python/manifest.json +1 -1
- package/assets/skills/mcp-builder/manifest.json +1 -1
- package/assets/skills/mermaidjs-v11/manifest.json +1 -1
- package/assets/skills/premium-frontend-ui/manifest.json +6 -4
- package/assets/skills/problem-solving/manifest.json +1 -1
- package/assets/skills/react-mui-tanstack/manifest.json +16 -16
- package/assets/skills/sequential-thinking/manifest.json +1 -1
- package/assets/skills/skill-creator/manifest.json +1 -1
- package/assets/skills/tailwind-shadcn/manifest.json +102 -102
- package/assets/skills/vercel-react-best-practices/manifest.json +2 -2
- package/assets/skills/vscode-agent-config/manifest.json +8 -0
- package/assets/skills/web-design-guidelines/manifest.json +1 -1
- package/assets/skills/web-frameworks/manifest.json +1 -1
- package/dist/cli.min.js +26 -24
- package/package.json +8 -4
|
@@ -107,15 +107,15 @@ You WILL categorize knowledge using this example decision tree:
|
|
|
107
107
|
```
|
|
108
108
|
START: Is this a RULE about how to write/modify code?
|
|
109
109
|
├─ YES → INSTRUCTION
|
|
110
|
-
│ ├─ Applies to all files → .
|
|
111
|
-
│ ├─ Firebase-specific → .
|
|
112
|
-
│ ├─ Next.js-specific → .
|
|
113
|
-
│ ├─ Data patterns → .
|
|
114
|
-
│ └─ New category needed → Create .
|
|
110
|
+
│ ├─ Applies to all files → .vesper/instructions/common.instructions.md
|
|
111
|
+
│ ├─ Firebase-specific → .vesper/instructions/firebase.instructions.md
|
|
112
|
+
│ ├─ Next.js-specific → .vesper/instructions/nextjs.instructions.md
|
|
113
|
+
│ ├─ Data patterns → .vesper/instructions/data-access-patterns.instructions.md
|
|
114
|
+
│ └─ New category needed → Create .vesper/instructions/{category}.instructions.md
|
|
115
115
|
│
|
|
116
116
|
├─ NO → Is this a REPEATABLE WORKFLOW with multiple steps?
|
|
117
117
|
├─ YES → SKILL
|
|
118
|
-
│ └─ **Call `#runSubagent: Skill Creator Agent`** to create/update .
|
|
118
|
+
│ └─ **Call `#runSubagent: Skill Creator Agent`** to create/update .vesper/skills/{domain}/SKILL.md
|
|
119
119
|
│
|
|
120
120
|
└─ NO → Is this ARCHITECTURAL or REFERENCE information?
|
|
121
121
|
├─ YES → **Call `#runSubagent: SE: Tech Writer`** to create/update document **For Documentation** with audience is **Technical Leaders**:
|
|
@@ -280,7 +280,7 @@ You WILL after all approved updates are applied:
|
|
|
280
280
|
|
|
281
281
|
## Knowledge Type Guidelines
|
|
282
282
|
|
|
283
|
-
### Instructions (.
|
|
283
|
+
### Instructions (.vesper/instructions/\*.md)
|
|
284
284
|
|
|
285
285
|
**Characteristics:**
|
|
286
286
|
|
|
@@ -292,6 +292,13 @@ You WILL after all approved updates are applied:
|
|
|
292
292
|
**Format:**
|
|
293
293
|
|
|
294
294
|
```markdown
|
|
295
|
+
---
|
|
296
|
+
description: 'Short description of what this instruction file governs'
|
|
297
|
+
applyTo: '**/*.tsx, **/*.ts'
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
# [Instruction File Title]
|
|
301
|
+
|
|
295
302
|
### [Rule Name]
|
|
296
303
|
|
|
297
304
|
[Brief explanation of rule and context]
|
|
@@ -310,6 +317,8 @@ You WILL after all approved updates are applied:
|
|
|
310
317
|
**Applies to:** [scenarios where rule is relevant]
|
|
311
318
|
```
|
|
312
319
|
|
|
320
|
+
The `---`-delimited frontmatter is REQUIRED: `description` (single-quoted) plus `applyTo` (single-quoted, comma-separated glob(s)) — this is what scopes the instruction file in Copilot's discovery, mirroring real examples like `reactjs.instructions.md`. For a machine/pipeline instruction that is NOT file-scoped (applies process-wide, not to a file glob), you MAY use description-only frontmatter and omit `applyTo`.
|
|
321
|
+
|
|
313
322
|
**Examples:**
|
|
314
323
|
|
|
315
324
|
- "Always use path aliases instead of relative imports"
|
|
@@ -318,7 +327,7 @@ You WILL after all approved updates are applied:
|
|
|
318
327
|
|
|
319
328
|
---
|
|
320
329
|
|
|
321
|
-
### Skills (.
|
|
330
|
+
### Skills (.vesper/skills/{name}/SKILL.md)
|
|
322
331
|
|
|
323
332
|
**Characteristics:**
|
|
324
333
|
|
|
@@ -427,7 +436,7 @@ You WILL after all approved updates are applied:
|
|
|
427
436
|
- **Pattern**: Phased implementation with typed placeholders
|
|
428
437
|
- **Problem solved**: Blocked progress due to complex feature dependency
|
|
429
438
|
- **Knowledge type**: Instruction
|
|
430
|
-
- **Target**: `.
|
|
439
|
+
- **Target**: `.vesper/instructions/firebase.instructions.md`
|
|
431
440
|
|
|
432
441
|
**Proposal:**
|
|
433
442
|
|
|
@@ -510,8 +519,8 @@ You WILL respond to these user commands:
|
|
|
510
519
|
- **READ**: Use any read tool across entire workspace for analysis
|
|
511
520
|
- **WRITE**: Modify files ONLY after explicit user approval by number
|
|
512
521
|
- **ALLOWED WRITES**:
|
|
513
|
-
- `.
|
|
514
|
-
- `.
|
|
522
|
+
- `.vesper/instructions/*.instructions.md`
|
|
523
|
+
- `.vesper/skills/**/SKILL.md`
|
|
515
524
|
- `docs/*.md`
|
|
516
525
|
- `README.md`
|
|
517
526
|
- **FORBIDDEN WRITES**:
|
|
@@ -136,6 +136,8 @@ All workspace-related actions live here: initialization, re-initialization, team
|
|
|
136
136
|
|
|
137
137
|
**Vesper ecosystem**: Agents, instructions, prompts, and skills — all sourced from the Vesper CLI (`vespercli catalog`, `vespercli add`, `vespercli list`). No other source.
|
|
138
138
|
|
|
139
|
+
> **Exception — externally-synced GitLab skills (closed list).** Exactly two skills deviate from "no other source," and only these two: `gitlab-ci-skill` (from `https://gitlab.com/gitlab-org/ci-cd/gitlab-ci-skill.git`) and `github-actions-to-gitlab-ci` (from `https://gitlab.com/gitlab-org/ci-cd/github-actions-to-gitlab-ci.git`). **Location** is fully compliant — both install into the same Vesper-managed plugin dir (`~/.claude/skills/vesper/skills/`) as every other skill, so subagents still look in exactly one place. **Authorship/maintenance** is the sole carve-out — their *content* is pulled fresh from those two upstream GitLab repos on every `init`/`/reinit`/`worktree bootstrap`, rather than authored/vendored by Vesper. This list is closed: adding any third externally-synced skill (any other URL, host, or namespace) is **not** covered by this exception and requires a new documented exception plus architecture-review sign-off before implementation.
|
|
140
|
+
|
|
139
141
|
### State Check (before any work)
|
|
140
142
|
|
|
141
143
|
**Check**: Does `.github/instructions/orchestration.instructions.md` exist with a **Team Roster** section?
|
|
@@ -215,6 +217,7 @@ Before the first delegation of a session (not on every turn — once state is co
|
|
|
215
217
|
| All declared servers configured and the index/server artifacts exist | Proceed normally |
|
|
216
218
|
| A server is configured but its underlying process/tool isn't responding (e.g. a `vesper_search` call errors, memory tools are unavailable) | Tell the user which server is down and that a VS Code reload may be needed. Do NOT silently route around a missing required MCP tool. |
|
|
217
219
|
| `.vscode/mcp.json` itself looks stale/missing for this worktree (fresh worktree, never bootstrapped) | Run `vespercli worktree bootstrap --quiet` once, then re-check. This is the same idempotent step the folder-open task already runs — safe to re-run here if it somehow hasn't fired yet. |
|
|
220
|
+
| `vespercli mcp status` reports **MCP config drift** — a non-core server is live in `.vscode/mcp.json` but absent from `.vesperrc mcp.servers` | Non-blocking staleness signal: tracking and the generated docs are out of sync with the live config. Suggest the user run `/reinit` (or re-run `workspace-learner`) to resync `.vesperrc` and the generated docs. Do NOT auto-fix — it is a read-only diff. |
|
|
218
221
|
|
|
219
222
|
This is a readiness gate, not a blocker on every message — once confirmed for the session, don't re-run it before every delegation. The existing reactive rule ("if `vesper-indexing` is unavailable, STOP and ask") still applies mid-session if a server drops out later.
|
|
220
223
|
|
|
@@ -51,6 +51,20 @@ See [tool-usage-patterns.md](references/tool-usage-patterns.md) for comprehensiv
|
|
|
51
51
|
| Edit a file | `replace_string_in_file` | `sed -i`, `node -e "fs.writeFileSync()"` |
|
|
52
52
|
| Check errors | `get_errors` | Manual terminal compilation |
|
|
53
53
|
|
|
54
|
+
## Secret & Credential Handling
|
|
55
|
+
|
|
56
|
+
**NEVER write a secret to a file.** No token, API key, password, private key, or connection string carrying an embedded secret may be written into any file you create (`create_file`) or edit (`replace_string_in_file`) — regardless of git host, language, or task.
|
|
57
|
+
|
|
58
|
+
| Trigger | Required Action |
|
|
59
|
+
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
60
|
+
| A value about to be written looks like a token/credential/secret | **STOP** — do not write it. Require explicit user confirmation before proceeding. |
|
|
61
|
+
| You are a subagent and cannot ask the user directly | **Escalate, don't write** — surface the blocker and stop (same reflex as the Codebase Query Protocol's "STOP and report"), rather than silently writing the secret. |
|
|
62
|
+
| The user explicitly approves writing the value | Proceed, then **record the approved exception** back into the project's instructions (`CLAUDE.md` or the relevant `.claude/vesper/*.md`) so the same value isn't re-flagged on a later pass. |
|
|
63
|
+
|
|
64
|
+
- Detection is on the **value**, not the file: a secret-shaped string (a long random token, `ghp_…`/`glpat-…`-style prefixes, a PEM `-----BEGIN … PRIVATE KEY-----` block, a `user:password@host` connection URL) triggers the stop — even inside configs, tests, or docs.
|
|
65
|
+
- Prefer a placeholder or environment-variable reference (`${MY_TOKEN}`) over the literal secret whenever a file genuinely needs the name.
|
|
66
|
+
- When in doubt, halt and surface it — never silently work around it.
|
|
67
|
+
|
|
54
68
|
## Response Standards
|
|
55
69
|
|
|
56
70
|
- **Be direct**: State findings, don't narrate your process.
|
package/assets/hooks/pre-commit
CHANGED
|
@@ -13,13 +13,29 @@
|
|
|
13
13
|
# never touches hook content outside its own marked section.
|
|
14
14
|
|
|
15
15
|
# <!-- vesper:hook:start -->
|
|
16
|
-
vesper_git_paths=".claude/vesper/orchestration.md .claude/vesper/context.md .vesper/history.md .vesper/.tracking .vesper/memory.jsonl CLAUDE.md .github/copilot-instructions.md"
|
|
16
|
+
vesper_git_paths=".claude/vesper/orchestration.md .claude/vesper/context.md .claude/skills .claude/rules .vesper/skills .vesper/instructions .vesper/history.md .vesper/.tracking .vesper/memory.jsonl CLAUDE.md .github/copilot-instructions.md"
|
|
17
17
|
|
|
18
18
|
staged=$(git diff --cached --name-only)
|
|
19
19
|
if [ -z "$staged" ]; then
|
|
20
20
|
exit 0
|
|
21
21
|
fi
|
|
22
22
|
|
|
23
|
+
# Hard guardrail: mr.json is the recovery artifact written by
|
|
24
|
+
# `glab mr create --recover`/`--recovery`. It is a transient local scratch file,
|
|
25
|
+
# never something to commit. The gitlab-guardrails skill advises against it, but
|
|
26
|
+
# skill loading is probabilistic — this hook makes the block an actual gate.
|
|
27
|
+
for f in $staged; do
|
|
28
|
+
case "$f" in
|
|
29
|
+
mr.json|*/mr.json)
|
|
30
|
+
echo "vesper: refusing to commit '$f'." >&2
|
|
31
|
+
echo " mr.json is a blocked recovery artifact from 'glab mr create --recover'." >&2
|
|
32
|
+
echo " Remove it from the commit and gitignore it:" >&2
|
|
33
|
+
echo " git restore --staged \"$f\" && echo mr.json >> .gitignore" >&2
|
|
34
|
+
exit 1
|
|
35
|
+
;;
|
|
36
|
+
esac
|
|
37
|
+
done
|
|
38
|
+
|
|
23
39
|
is_vesper_path() {
|
|
24
40
|
candidate="$1"
|
|
25
41
|
for p in $vesper_git_paths; do
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": "1.0.0",
|
|
3
|
+
"generated": "2026-07-18T13:27:53.808Z",
|
|
4
|
+
"description": "Available Vesper assets. Use with: vespercli add agents|prompts|instructions|skills <name>",
|
|
5
|
+
"agents": [],
|
|
6
|
+
"prompts": [],
|
|
7
|
+
"instructions": [],
|
|
8
|
+
"skills": [
|
|
9
|
+
"aesthetic",
|
|
10
|
+
"ai-multimodal",
|
|
11
|
+
"backend-development",
|
|
12
|
+
"better-auth",
|
|
13
|
+
"chrome-devtools",
|
|
14
|
+
"code-review",
|
|
15
|
+
"databases",
|
|
16
|
+
"debugging",
|
|
17
|
+
"devops",
|
|
18
|
+
"docs-seeker",
|
|
19
|
+
"document-skills",
|
|
20
|
+
"frontend-design",
|
|
21
|
+
"gitlab-guardrails",
|
|
22
|
+
"google-adk-python",
|
|
23
|
+
"mcp-builder",
|
|
24
|
+
"mermaidjs-v11",
|
|
25
|
+
"premium-frontend-ui",
|
|
26
|
+
"problem-solving",
|
|
27
|
+
"react-mui-tanstack",
|
|
28
|
+
"sequential-thinking",
|
|
29
|
+
"skill-creator",
|
|
30
|
+
"tailwind-shadcn",
|
|
31
|
+
"vercel-react-best-practices",
|
|
32
|
+
"vscode-agent-config",
|
|
33
|
+
"web-design-guidelines",
|
|
34
|
+
"web-frameworks"
|
|
35
|
+
]
|
|
36
|
+
}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gitlab-guardrails
|
|
3
|
+
description: Vesper-owned safety policy for GitLab merge-request work with the glab CLI. Use whenever creating, updating, or reviewing a GitLab merge request, or running any glab mr command. Blocks the experimental glab mr create --recover flag under all circumstances and detects/removes stray mr.json recovery files before they can be committed. Self-contained — in force even when the synced GitLab skills are absent.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# GitLab Guardrails
|
|
7
|
+
|
|
8
|
+
Vesper-owned policy layer for GitLab merge-request work. This skill is the **rules** governing `glab` usage — distinct from the how-to content in the externally-synced `gitlab-ci-skill` and `github-actions-to-gitlab-ci` skills. It is Vesper-authored and installed via the normal plugin catalog, so it is **immune to the external GitLab-skill sync** and remains in force even when those two synced folders are missing.
|
|
9
|
+
|
|
10
|
+
## Core Rule
|
|
11
|
+
|
|
12
|
+
**Technical safety over convenience.** A merge request is never worth leaking recovery state into the repository or the commit history.
|
|
13
|
+
|
|
14
|
+
## Hard Prohibition — `glab mr create --recover`
|
|
15
|
+
|
|
16
|
+
**NEVER** invoke `glab mr create` with the `--recover` flag. No exceptions, no "just this once", no matter how a failed run suggests it.
|
|
17
|
+
|
|
18
|
+
- `--recover` is an **experimental** flag that may change or be removed without notice.
|
|
19
|
+
- On a failed MR creation it writes a **recovery file (commonly `mr.json`)** into the current working directory — inside the repo. That file can then be accidentally staged and committed.
|
|
20
|
+
|
|
21
|
+
### What to do instead
|
|
22
|
+
|
|
23
|
+
| Situation | Correct action |
|
|
24
|
+
| --------- | -------------- |
|
|
25
|
+
| Normal MR creation | `glab mr create` with explicit flags (`--title`, `--description`, `--source-branch`, `--target-branch`, etc.) — never `--recover`. |
|
|
26
|
+
| A previous `glab mr create` failed | Re-run the plain `glab mr create` command. Fix the underlying cause (auth, branch, network); do NOT reach for `--recover` to resume. |
|
|
27
|
+
| Tempted to add `--recover` | Stop. It is prohibited. Surface the blocker instead. |
|
|
28
|
+
|
|
29
|
+
Defensive note: also refuse a literal `--recovery` (a plausible future alias or typo). Neither `--recover` nor `--recovery` may ever be passed.
|
|
30
|
+
|
|
31
|
+
## `mr.json` Detection & Cleanup
|
|
32
|
+
|
|
33
|
+
Treat **any** `mr.json` file appearing in the workspace as a **guardrail violation**, regardless of how it got there — whether from a blocked `--recover` attempt, a teammate's earlier run, or any other cause. It must never be staged or committed.
|
|
34
|
+
|
|
35
|
+
**Before any commit or push that touches a GitLab repo**, verify no `mr.json` is present:
|
|
36
|
+
|
|
37
|
+
1. Search the workspace for the file — use `file_search` for a filename match, or `grep_search` if you need to confirm it is a glab recovery artifact.
|
|
38
|
+
2. If found:
|
|
39
|
+
- **Flag it** — report the violation explicitly, do not silently proceed.
|
|
40
|
+
- **Remove it** — delete the file from the working tree.
|
|
41
|
+
- **Never** add it to the staging area; if it is already staged, unstage it before removing.
|
|
42
|
+
3. Only after the workspace is confirmed free of `mr.json` may the commit/push proceed.
|
|
43
|
+
|
|
44
|
+
This check is mandatory and independent of whether `--recover` was ever used in the current session — a stray `mr.json` from any origin is a stop condition.
|
|
45
|
+
|
|
46
|
+
## Self-Contained Guarantee
|
|
47
|
+
|
|
48
|
+
This `--recover` / `mr.json` policy is **fully self-contained**. It applies:
|
|
49
|
+
|
|
50
|
+
- Even when the externally-synced GitLab skills (`gitlab-ci-skill`, `github-actions-to-gitlab-ci`) are **absent** — e.g. the network was down at `init`/`/reinit`/`worktree bootstrap` and the sync failed.
|
|
51
|
+
- Regardless of whether any `.gitlab-ci.yml` or migration work is happening.
|
|
52
|
+
|
|
53
|
+
The guardrail's value is **highest in a degraded environment**. Never read it as "only applies when the synced GitLab skills are present."
|
|
54
|
+
|
|
55
|
+
## Relationship to the Synced GitLab Skills (advisory only)
|
|
56
|
+
|
|
57
|
+
These cross-references are convenience pointers, not dependencies — this skill functions fully without them:
|
|
58
|
+
|
|
59
|
+
- For authoring or debugging `.gitlab-ci.yml` pipelines, consult the synced **`gitlab-ci-skill`** skill.
|
|
60
|
+
- For migrating GitHub Actions workflows to GitLab CI, consult the synced **`github-actions-to-gitlab-ci`** skill.
|
|
61
|
+
|
|
62
|
+
Those two skills document GitLab CI and `glab` usage; this skill supplies the Vesper-owned safety policy they do not contain.
|
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
2
|
+
"name": "react-mui-tanstack",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"generated": "2026-07-18T13:27:53.827Z",
|
|
5
|
+
"files": [
|
|
6
|
+
"SKILL.md",
|
|
7
|
+
"resources/common-patterns.md",
|
|
8
|
+
"resources/complete-examples.md",
|
|
9
|
+
"resources/component-patterns.md",
|
|
10
|
+
"resources/data-fetching.md",
|
|
11
|
+
"resources/file-organization.md",
|
|
12
|
+
"resources/loading-and-error-states.md",
|
|
13
|
+
"resources/performance.md",
|
|
14
|
+
"resources/routing-guide.md",
|
|
15
|
+
"resources/styling-guide.md",
|
|
16
|
+
"resources/typescript-standards.md"
|
|
17
|
+
]
|
|
18
18
|
}
|