viepilot 2.23.0 → 2.41.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/CHANGELOG.md +195 -0
- package/README.md +6 -6
- package/bin/viepilot.cjs +108 -1
- package/bin/vp-tools.cjs +109 -0
- package/docs/brainstorm/session-2026-04-20.md +261 -0
- package/docs/skills-reference.md +22 -0
- package/docs/user/features/adapters.md +2 -2
- package/docs/user/features/scaffold-first.md +62 -0
- package/docs/user/features/skill-registry.md +125 -0
- package/lib/adapters/antigravity.cjs +5 -4
- package/lib/skill-installer.cjs +274 -0
- package/lib/skill-registry.cjs +212 -0
- package/lib/viepilot-update.cjs +113 -0
- package/package.json +1 -1
- package/skills/vp-audit/SKILL.md +57 -9
- package/skills/vp-auto/SKILL.md +44 -0
- package/skills/vp-brainstorm/SKILL.md +108 -1
- package/skills/vp-crystallize/SKILL.md +72 -0
- package/skills/vp-debug/SKILL.md +27 -0
- package/skills/vp-docs/SKILL.md +27 -0
- package/skills/vp-evolve/SKILL.md +59 -6
- package/skills/vp-info/SKILL.md +27 -0
- package/skills/vp-pause/SKILL.md +27 -0
- package/skills/vp-proposal/SKILL.md +27 -0
- package/skills/vp-request/SKILL.md +52 -6
- package/skills/vp-resume/SKILL.md +27 -0
- package/skills/vp-rollback/SKILL.md +27 -0
- package/skills/vp-skills/SKILL.md +301 -0
- package/skills/vp-status/SKILL.md +27 -0
- package/skills/vp-task/SKILL.md +27 -0
- package/skills/vp-ui-components/SKILL.md +27 -0
- package/skills/vp-update/SKILL.md +27 -0
- package/templates/phase/TASK.md +7 -0
- package/templates/project/PROJECT-CONTEXT.md +76 -0
- package/workflows/audit.md +131 -0
- package/workflows/autonomous.md +140 -0
- package/workflows/brainstorm.md +1025 -9
- package/workflows/crystallize.md +528 -3
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
# Brainstorm Session — 2026-04-20
|
|
2
|
+
|
|
3
|
+
## Topic
|
|
4
|
+
**ViePilot Skill Registry System** — Third-party skill installation + scan-skills command + workflow skill integration (brainstorm / crystallize / vp-auto gates)
|
|
5
|
+
|
|
6
|
+
## Status
|
|
7
|
+
In Progress
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Problem Statement
|
|
12
|
+
|
|
13
|
+
ViePilot hiện tại chỉ dùng built-in `vp-*` skills. Khi user muốn xây dựng UI-Direction phức tạp hơn (ví dụ dùng design system cụ thể, component library, hay frontend framework chuyên biệt), không có cơ chế nào để bổ sung context chuyên sâu từ external skills.
|
|
14
|
+
|
|
15
|
+
Vấn đề cụ thể:
|
|
16
|
+
1. Không có cách cài thêm skills từ bên thứ 3 (npm, GitHub, local)
|
|
17
|
+
2. ViePilot không biết skills nào đang có sẵn trên máy
|
|
18
|
+
3. Workflow (brainstorm / crystallize / vp-auto) không thể tận dụng skill context ngoài vp-* namespace
|
|
19
|
+
4. Quyết định "dùng skill nào" không có điểm lock — vp-auto phải hỏi lại hoặc đoán
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Proposed Solution: Skill Registry System
|
|
24
|
+
|
|
25
|
+
### Core Concept
|
|
26
|
+
|
|
27
|
+
Ba tầng hoạt động:
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
[Install] vp-tools install-skill <source> → cài skill vào adapter dirs
|
|
31
|
+
[Discover] vp-tools scan-skills → quét + index toàn bộ skills
|
|
32
|
+
[Apply] brainstorm → crystallize → auto → dùng skills theo pipeline
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### Tầng 1 — Installation (multi-channel)
|
|
36
|
+
|
|
37
|
+
`vp-tools install-skill <source>` hỗ trợ:
|
|
38
|
+
|
|
39
|
+
| Channel | Syntax | Example |
|
|
40
|
+
|---------|--------|---------|
|
|
41
|
+
| npm | `npm:package-name` hoặc bare name | `vp-tools install-skill @vp-skills/frontend-design` |
|
|
42
|
+
| GitHub | `github:org/repo` | `vp-tools install-skill github:myorg/vp-skill-tailwind` |
|
|
43
|
+
| Local | `./path` hoặc absolute path | `vp-tools install-skill ./my-skill` |
|
|
44
|
+
|
|
45
|
+
Sau khi install → tự động chạy `scan-skills` để cập nhật registry.
|
|
46
|
+
|
|
47
|
+
Commands bổ sung:
|
|
48
|
+
- `vp-tools uninstall-skill <id>` — xóa khỏi tất cả adapter dirs
|
|
49
|
+
- `vp-tools list-skills` — hiển thị skills đã cài + version + source
|
|
50
|
+
- `vp-tools update-skill <id>` — cập nhật từ source gốc
|
|
51
|
+
|
|
52
|
+
### Tầng 2 — Scanner & Registry
|
|
53
|
+
|
|
54
|
+
`vp-tools scan-skills` quét toàn bộ adapter dirs:
|
|
55
|
+
- `~/.claude/skills/` (Claude Code)
|
|
56
|
+
- `~/.cursor/skills/` (Cursor)
|
|
57
|
+
- `~/.codex/skills/` (Codex)
|
|
58
|
+
- `~/.antigravity/skills/` (Antigravity)
|
|
59
|
+
|
|
60
|
+
Output: `~/.viepilot/skill-registry.json`
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"version": "1.0",
|
|
65
|
+
"last_scan": "2026-04-20T10:30:00Z",
|
|
66
|
+
"scan_paths": ["~/.claude/skills/", "~/.cursor/skills/"],
|
|
67
|
+
"skills": [
|
|
68
|
+
{
|
|
69
|
+
"id": "frontend-design",
|
|
70
|
+
"name": "Frontend Design",
|
|
71
|
+
"source": "npm:@vp-skills/frontend-design",
|
|
72
|
+
"version": "1.2.0",
|
|
73
|
+
"description": "...",
|
|
74
|
+
"capabilities": ["ui-generation", "component-design", "responsive-layout"],
|
|
75
|
+
"tags": ["ui", "design", "frontend", "css", "html"],
|
|
76
|
+
"best_practices": ["Mobile-first", "Design tokens", "BEM naming"],
|
|
77
|
+
"adapters": ["claude-code", "cursor"],
|
|
78
|
+
"installed_paths": {
|
|
79
|
+
"claude-code": "~/.claude/skills/frontend-design/",
|
|
80
|
+
"cursor": "~/.cursor/skills/frontend-design/"
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
]
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Tầng 3 — SKILL.md Extended Format
|
|
88
|
+
|
|
89
|
+
Third-party skills (và vp-* skills nếu muốn) thêm 3 sections mới vào SKILL.md:
|
|
90
|
+
|
|
91
|
+
```markdown
|
|
92
|
+
## Capabilities
|
|
93
|
+
- ui-generation
|
|
94
|
+
- component-design
|
|
95
|
+
- responsive-layout
|
|
96
|
+
|
|
97
|
+
## Tags
|
|
98
|
+
ui, design, frontend, css, html, tailwind
|
|
99
|
+
|
|
100
|
+
## Best Practices
|
|
101
|
+
- Use design tokens for consistency across components
|
|
102
|
+
- Mobile-first: design breakpoints from 320px up
|
|
103
|
+
- BEM naming convention for CSS classes
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Scanner đọc các sections này để index. Skills không có sections mới vẫn được scan (fallback: parse description + content tự động).
|
|
107
|
+
|
|
108
|
+
### Tầng 4 — Workflow Integration Pipeline
|
|
109
|
+
|
|
110
|
+
#### A. Brainstorm → Silent Skill Application (UI-Direction)
|
|
111
|
+
|
|
112
|
+
Khi brainstorm có UI signals (keywords: `component`, `design`, `layout`, `screen`, `UI`, v.v.):
|
|
113
|
+
- Load `~/.viepilot/skill-registry.json`
|
|
114
|
+
- Match skills có `capabilities` phù hợp (e.g., `ui-generation`, `component-design`)
|
|
115
|
+
- **Silent apply**: tự động include best practices từ matched skills vào HTML generation
|
|
116
|
+
- Record vào `notes.md`: `## skills_used` section
|
|
117
|
+
|
|
118
|
+
```yaml
|
|
119
|
+
## skills_used
|
|
120
|
+
- id: frontend-design
|
|
121
|
+
version: 1.2.0
|
|
122
|
+
trigger: ui-generation signal
|
|
123
|
+
applied_at: brainstorm-session
|
|
124
|
+
best_practices_applied:
|
|
125
|
+
- Mobile-first
|
|
126
|
+
- Design tokens
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Không hỏi user — chạy ngầm như Background UI Extraction.
|
|
130
|
+
|
|
131
|
+
#### B. Crystallize → Skill Decision Lock Gate
|
|
132
|
+
|
|
133
|
+
Bước mới trong `vp-crystallize` (sau scope lock, trước generate SPEC):
|
|
134
|
+
|
|
135
|
+
1. Đọc `notes.md` → `## skills_used` của session đó
|
|
136
|
+
2. Hiển thị danh sách skills đã/sẽ được dùng
|
|
137
|
+
3. User confirm: required vs optional per phase/task
|
|
138
|
+
4. Ghi vào `PROJECT-CONTEXT.md`:
|
|
139
|
+
|
|
140
|
+
```markdown
|
|
141
|
+
## Skills
|
|
142
|
+
|
|
143
|
+
| Skill | Source | Required | Phases | Rationale |
|
|
144
|
+
|-------|--------|----------|--------|-----------|
|
|
145
|
+
| frontend-design | npm:@vp-skills/frontend-design | required | 1, 2 | UI-Direction HTML generation — design token best practices |
|
|
146
|
+
| tailwind-guide | github:org/vp-tailwind | optional | 2 | Phase 2 styling layer |
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
**Lý do lock ở crystallize:** vp-auto là execution-only — nó đọc SPEC và chạy, không ra quyết định. Tất cả quyết định về "dùng skill nào" phải được lock trước khi vp-auto bắt đầu.
|
|
150
|
+
|
|
151
|
+
#### C. vp-auto → Silent Skill Execution
|
|
152
|
+
|
|
153
|
+
vp-auto đọc `## Skills` từ `PROJECT-CONTEXT.md`:
|
|
154
|
+
- Với mỗi task, kiểm tra skills `required` trong phases tương ứng
|
|
155
|
+
- Load best practices từ skill registry
|
|
156
|
+
- Include context vào execution prompt — **không hỏi lại user**
|
|
157
|
+
- Ghi vào task output: `skills_applied: [frontend-design@1.2.0]`
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Decisions
|
|
162
|
+
|
|
163
|
+
| Decision | Options Considered | Chosen | Rationale |
|
|
164
|
+
|----------|--------------------|--------|-----------|
|
|
165
|
+
| Skill source channels | npm-only / all channels | All channels (npm + github + local) | Flexibility cho cả published và WIP skills |
|
|
166
|
+
| Scanner scope | ViePilot-only dirs / all adapter dirs | All adapter dirs | Discover tất cả skills user đã cài qua bất kỳ tool nào |
|
|
167
|
+
| Gate model | Required block / heuristic prompt / silent / hybrid | Silent auto-apply + crystallize-time lock | vp-auto không hỏi lại; quyết định từ crystallize. Nhất quán với ui-direction guard |
|
|
168
|
+
| SKILL.md format | Giữ nguyên / extend / file riêng | Extend — thêm Capabilities/Tags/Best Practices | Backward compat; scanner vẫn parse skills cũ |
|
|
169
|
+
| Lock storage | SPEC.md per-task / PROJECT-CONTEXT.md ## Skills / file riêng | PROJECT-CONTEXT.md ## Skills | Tương tự ## Tech Stack — project-level; dễ đọc cho vp-auto |
|
|
170
|
+
| Phase 1 target | Scanner / Installer / Brainstorm integration | Scanner + registry first | Nền tảng cho mọi tính năng phía sau |
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## Open Questions
|
|
175
|
+
|
|
176
|
+
| ID | Question | Priority | Due |
|
|
177
|
+
|----|----------|----------|-----|
|
|
178
|
+
| Q1 | Có cần `vp-tools publish-skill` để user publish skill lên npm không? | low | next milestone |
|
|
179
|
+
| Q2 | Skill versioning: nếu skill update, best practices thay đổi — có cần re-crystallize không? | medium | Phase 4 design |
|
|
180
|
+
| Q3 | Skill conflict: 2 skills có cùng capability, workflow ưu tiên cái nào? | medium | Phase 3 design |
|
|
181
|
+
| Q4 | Có cần một "official ViePilot skills registry" (marketplace) hay chỉ dựa vào npm search? | low | future |
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## Phases
|
|
186
|
+
|
|
187
|
+
### Phase 1 — Skill Registry Foundation
|
|
188
|
+
**Goal**: `vp-tools scan-skills` + `~/.viepilot/skill-registry.json` + extended SKILL.md format spec
|
|
189
|
+
|
|
190
|
+
Tasks:
|
|
191
|
+
1. `lib/skill-registry.cjs` — scanner: traverse adapter dirs, parse SKILL.md (extended + legacy), build JSON
|
|
192
|
+
2. `bin/viepilot.cjs` — add `scan-skills` subcommand + `list-skills` display
|
|
193
|
+
3. `docs/user/features/skill-registry.md` — extended SKILL.md format spec + scanner docs
|
|
194
|
+
4. `tests/unit/vp-skill-registry.test.js` — 15+ contract tests (scan, parse, index, legacy compat)
|
|
195
|
+
|
|
196
|
+
Target version: **2.26.0**
|
|
197
|
+
|
|
198
|
+
### Phase 2 — Third-party Skill Installation
|
|
199
|
+
**Goal**: `vp-tools install-skill` (npm + github + local) + `uninstall-skill` + `update-skill`
|
|
200
|
+
|
|
201
|
+
Tasks:
|
|
202
|
+
1. `lib/skill-installer.cjs` — multi-channel installer (npm exec + git clone + fs copy)
|
|
203
|
+
2. `bin/viepilot.cjs` — add `install-skill`, `uninstall-skill`, `update-skill` subcommands
|
|
204
|
+
3. Post-install hook: auto-run `scan-skills`
|
|
205
|
+
4. `tests/unit/vp-skill-installer.test.js` — 12+ tests (each channel, auto-scan trigger)
|
|
206
|
+
|
|
207
|
+
Target version: **2.27.0**
|
|
208
|
+
|
|
209
|
+
### Phase 3 — Brainstorm Integration (UI-Direction silent apply)
|
|
210
|
+
**Goal**: brainstorm.md detects UI signals → loads registry → silently applies matched skill best practices → records `## skills_used` in notes.md
|
|
211
|
+
|
|
212
|
+
Tasks:
|
|
213
|
+
1. `workflows/brainstorm.md` — add skill registry load step + signal matching logic + silent apply rule
|
|
214
|
+
2. `skills/vp-brainstorm/SKILL.md` — document skill integration behavior
|
|
215
|
+
3. `tests/unit/brainstorm-skill-integration.test.js` — 10+ tests
|
|
216
|
+
|
|
217
|
+
Target version: **2.28.0**
|
|
218
|
+
|
|
219
|
+
### Phase 4 — Crystallize Skill Decision Gate
|
|
220
|
+
**Goal**: crystallize.md new step → skill confirmation gate → `## Skills` in PROJECT-CONTEXT.md
|
|
221
|
+
|
|
222
|
+
Tasks:
|
|
223
|
+
1. `workflows/crystallize.md` — add skill gate step (read notes.md skills_used → AUQ confirm → write PROJECT-CONTEXT.md)
|
|
224
|
+
2. `templates/project/PROJECT-CONTEXT.md` — add `## Skills` section template
|
|
225
|
+
3. `skills/vp-crystallize/SKILL.md` — document skill gate
|
|
226
|
+
4. `tests/unit/crystallize-skill-gate.test.js` — 10+ tests
|
|
227
|
+
|
|
228
|
+
Target version: **2.29.0**
|
|
229
|
+
|
|
230
|
+
### Phase 5 — vp-auto Silent Skill Execution
|
|
231
|
+
**Goal**: autonomous.md reads `## Skills` from PROJECT-CONTEXT.md → per-task silent context injection
|
|
232
|
+
|
|
233
|
+
Tasks:
|
|
234
|
+
1. `workflows/autonomous.md` — add skill context load step + per-task skill injection rule
|
|
235
|
+
2. `skills/vp-auto/SKILL.md` — document silent skill execution
|
|
236
|
+
3. `tests/unit/autonomous-skill-execution.test.js` — 8+ tests
|
|
237
|
+
|
|
238
|
+
Target version: **2.30.0**
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## Background UI Extraction
|
|
243
|
+
|
|
244
|
+
Waiver — session topic is a framework feature (skill registry), not a consumer app UI. No UI Direction artifacts needed.
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## Project meta intake (FEAT-009)
|
|
249
|
+
|
|
250
|
+
Waiver — ViePilot framework repo; profile binding already exists.
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## Session Summary
|
|
255
|
+
|
|
256
|
+
- **Feature**: ViePilot Skill Registry System
|
|
257
|
+
- **Suggested ID**: FEAT-020
|
|
258
|
+
- **Scope**: 5 phases — registry/scanner → installer → brainstorm integration → crystallize gate → vp-auto execution
|
|
259
|
+
- **Key architectural decision**: Skills are **silent auto-apply** at brainstorm time; **locked at crystallize** time; **executed without re-asking** by vp-auto
|
|
260
|
+
- **Backward compat**: Existing SKILL.md files still work — scanner gracefully handles missing extended sections
|
|
261
|
+
- **First deliverable**: `vp-tools scan-skills` + `~/.viepilot/skill-registry.json` (Phase 1 → v2.26.0)
|
package/docs/skills-reference.md
CHANGED
|
@@ -525,3 +525,25 @@ Place custom `.pptx`/`.docx` files in `.viepilot/proposal-templates/` to overrid
|
|
|
525
525
|
```
|
|
526
526
|
|
|
527
527
|
Full guide: `docs/user/features/proposal.md`
|
|
528
|
+
|
|
529
|
+
---
|
|
530
|
+
|
|
531
|
+
## /vp-skills
|
|
532
|
+
|
|
533
|
+
**Purpose**: Agent-native global skill registry management — scan, list, install, uninstall, update, and inspect third-party skills from any project directory (ENH-062).
|
|
534
|
+
|
|
535
|
+
### Commands
|
|
536
|
+
| Command | Description |
|
|
537
|
+
|---------|-------------|
|
|
538
|
+
| `/vp-skills scan` | Refresh `~/.viepilot/skill-registry.json` by scanning all adapter dirs |
|
|
539
|
+
| `/vp-skills list` | Display indexed skills table |
|
|
540
|
+
| `/vp-skills install <src>` | Install from npm / `github:<user>/<repo>` / local path |
|
|
541
|
+
| `/vp-skills uninstall <id>` | Remove skill from all adapter directories |
|
|
542
|
+
| `/vp-skills update <id>` | Re-install from original source (`skill-meta.json`) |
|
|
543
|
+
| `/vp-skills info <id>` | Show capabilities, best_practices, and adapter paths |
|
|
544
|
+
|
|
545
|
+
### Notes
|
|
546
|
+
- Uses installed vp-tools binary (`~/.claude/viepilot/bin/vp-tools.cjs`) — works from any project directory.
|
|
547
|
+
- Fallback: `~/.cursor/viepilot/bin/vp-tools.cjs` for Cursor adapter.
|
|
548
|
+
- Registry file: `~/.viepilot/skill-registry.json` — shared across all projects.
|
|
549
|
+
- Confirmation AUQ prompt before destructive `uninstall` (Claude Code terminal only).
|
|
@@ -8,7 +8,7 @@ ViePilot supports multiple AI coding platforms via its adapter system (FEAT-013)
|
|
|
8
8
|
|------------|----------|------------|--------------|-------|--------------|
|
|
9
9
|
| `claude-code` | Claude Code *(default)* | `~/.claude/skills/` | `~/.claude/viepilot/` | ✅ Stop, PreToolUse, … | `/vp-status` |
|
|
10
10
|
| `cursor-agent` / `cursor-ide` | Cursor | `~/.cursor/skills/` | `~/.cursor/viepilot/` | — | `/vp-status` |
|
|
11
|
-
| `antigravity` | Google Antigravity | `~/.antigravity/skills/` | `~/.antigravity/viepilot/` | — | `/vp-status` |
|
|
11
|
+
| `antigravity` | Google Antigravity | `~/.gemini/antigravity/skills/` | `~/.gemini/antigravity/viepilot/` | — | `/vp-status` |
|
|
12
12
|
| `codex` | OpenAI Codex CLI | `~/.codex/skills/` | `~/.codex/viepilot/` | — | `$vp-status` |
|
|
13
13
|
| `copilot` | GitHub Copilot | `~/.config/gh-copilot/skills/` | `~/.config/gh-copilot/viepilot/` | — | `/vp-status` |
|
|
14
14
|
|
|
@@ -47,7 +47,7 @@ Skill source files use the neutral placeholder `{envToolDir}` in `execution_cont
|
|
|
47
47
|
At install time, `{envToolDir}` is replaced with each adapter's `executionContextBase`:
|
|
48
48
|
- `claude-code` → `.claude/viepilot`
|
|
49
49
|
- `cursor` → `.cursor/viepilot`
|
|
50
|
-
- `antigravity` → `.antigravity/viepilot`
|
|
50
|
+
- `antigravity` → `.gemini/antigravity/viepilot`
|
|
51
51
|
- `codex` → `.codex/viepilot`
|
|
52
52
|
- `copilot` → `.config/gh-copilot/viepilot`
|
|
53
53
|
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Scaffold-First Gate (BUG-020)
|
|
2
|
+
|
|
3
|
+
`vp-auto` enforces a **scaffold-first** rule for framework-based projects: when a task initializes a new project, the canonical scaffold command MUST run before any framework-generated files are created manually.
|
|
4
|
+
|
|
5
|
+
## How It Works
|
|
6
|
+
|
|
7
|
+
1. **Detection** — vp-auto detects "project setup" tasks by keywords in the task title/objective: "set up", "initialize", "create project", "scaffold", "bootstrap", "new project"
|
|
8
|
+
2. **Marker check** — checks for a framework marker file (e.g. `artisan` for Laravel, `manage.py` for Django) to determine if the project is already scaffolded
|
|
9
|
+
3. **Scaffold command** — if not yet scaffolded, runs the scaffold command from either:
|
|
10
|
+
- `~/.viepilot/stacks/{stack}/SUMMARY.md` → `## Scaffold` → `init_command:` field (takes priority)
|
|
11
|
+
- The built-in heuristic table in `workflows/autonomous.md`
|
|
12
|
+
4. **Block list** — refuses to create framework-native files (artisan, next.config.*, manage.py, nest-cli.json, pom.xml, etc.) without prior scaffold
|
|
13
|
+
|
|
14
|
+
## Adding a Scaffold Command to a Stack
|
|
15
|
+
|
|
16
|
+
In `~/.viepilot/stacks/{your-stack}/SUMMARY.md`, append:
|
|
17
|
+
|
|
18
|
+
```markdown
|
|
19
|
+
## Scaffold
|
|
20
|
+
|
|
21
|
+
init_command: composer create-project laravel/laravel {name}
|
|
22
|
+
marker_file: artisan
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Replace `{name}` with the project directory name placeholder — vp-auto substitutes the actual project name at runtime.
|
|
26
|
+
|
|
27
|
+
## Built-in Supported Stacks
|
|
28
|
+
|
|
29
|
+
| Stack | Scaffold command | Marker file |
|
|
30
|
+
|-------|-----------------|-------------|
|
|
31
|
+
| laravel | `composer create-project laravel/laravel {name}` | `artisan` |
|
|
32
|
+
| laravel-php84 | `composer create-project laravel/laravel:^11 {name}` | `artisan` |
|
|
33
|
+
| nextjs | `npx create-next-app@latest {name}` | `next.config.js` |
|
|
34
|
+
| nextjs-tailwind-shadcn-threejs | `npx create-next-app@latest {name} --typescript --tailwind --eslint --app` | `next.config.js` |
|
|
35
|
+
| nestjs | `npx @nestjs/cli new {name}` | `nest-cli.json` |
|
|
36
|
+
| rails | `rails new {name}` | `config/application.rb` |
|
|
37
|
+
| django | `django-admin startproject {name} .` | `manage.py` |
|
|
38
|
+
| spring-boot* | `spring init --dependencies=web,data-jpa,validation {name}` | `pom.xml` |
|
|
39
|
+
| nuxt / vuejs* | `npx nuxi@latest init {name}` | `nuxt.config.ts` |
|
|
40
|
+
| react | `npx create-react-app {name}` | `src/index.js` |
|
|
41
|
+
| electron | `npx create-electron-app {name}` | `electron-builder.yml` |
|
|
42
|
+
|
|
43
|
+
## Never-Handcraft Block List
|
|
44
|
+
|
|
45
|
+
The following files must never be created manually in a project setup task without first running the scaffold command:
|
|
46
|
+
|
|
47
|
+
- `artisan`, `composer.json` (Laravel)
|
|
48
|
+
- `next.config.js`, `next.config.ts`, `pages/_app.*`, `app/layout.*` (Next.js)
|
|
49
|
+
- `nest-cli.json`, `src/main.ts` + `tsconfig.json` combo (NestJS)
|
|
50
|
+
- `manage.py`, `wsgi.py`, `asgi.py` (Django)
|
|
51
|
+
- `config/application.rb`, `config/routes.rb`, `Gemfile` (Rails)
|
|
52
|
+
- `pom.xml` or `build.gradle` with Spring Boot starters
|
|
53
|
+
|
|
54
|
+
## Bypassing the Gate
|
|
55
|
+
|
|
56
|
+
To override the gate (e.g. the project is already partially set up), add to the task file under `## Implementation Notes`:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
scaffold_gate_waiver: project already scaffolded — artisan exists at {path}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Or at execution time, select "confirm project already scaffolded" at the control-point prompt.
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# Skill Registry
|
|
2
|
+
|
|
3
|
+
ViePilot can discover and index skills installed across all adapter directories. The registry powers workflow skill integration — brainstorm silently applies relevant skill best practices during UI-Direction sessions, crystallize locks skill decisions, and vp-auto executes with no re-prompting.
|
|
4
|
+
|
|
5
|
+
## Commands
|
|
6
|
+
|
|
7
|
+
| Command | Description |
|
|
8
|
+
|---------|-------------|
|
|
9
|
+
| `vp-tools scan-skills` | Scan all adapter dirs and write `~/.viepilot/skill-registry.json` |
|
|
10
|
+
| `vp-tools list-skills` | Display indexed skills from the registry |
|
|
11
|
+
| `vp-tools install-skill <source>` | Install a third-party skill *(Phase 91 — coming soon)* |
|
|
12
|
+
|
|
13
|
+
## Extended SKILL.md Format
|
|
14
|
+
|
|
15
|
+
Third-party skills (and built-in vp-* skills) can add optional metadata sections to their `SKILL.md`:
|
|
16
|
+
|
|
17
|
+
```markdown
|
|
18
|
+
## Capabilities
|
|
19
|
+
- ui-generation
|
|
20
|
+
- component-design
|
|
21
|
+
- responsive-layout
|
|
22
|
+
|
|
23
|
+
## Tags
|
|
24
|
+
ui, design, frontend, css, html
|
|
25
|
+
|
|
26
|
+
## Best Practices
|
|
27
|
+
- Mobile-first: design breakpoints from 320px up
|
|
28
|
+
- Use design tokens for consistency across components
|
|
29
|
+
- BEM naming convention for CSS class names
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### Section rules
|
|
33
|
+
|
|
34
|
+
| Section | Format | Description |
|
|
35
|
+
|---------|--------|-------------|
|
|
36
|
+
| `## Capabilities` | One capability per line (`- item`) | Machine-readable ability tags used for skill matching |
|
|
37
|
+
| `## Tags` | Comma-separated or one per line | Human-readable keywords for discovery |
|
|
38
|
+
| `## Best Practices` | One practice per line (`- item`) | Applied silently when skill is matched in brainstorm/vp-auto |
|
|
39
|
+
|
|
40
|
+
All sections are **optional** — skills without them are still indexed and available.
|
|
41
|
+
|
|
42
|
+
### Backward compatibility
|
|
43
|
+
|
|
44
|
+
Existing `SKILL.md` files that do not contain these sections continue to work without modification. The scanner indexes them with empty `capabilities`, `tags`, and `best_practices` arrays and marks them as `(legacy — no capabilities)` in `list-skills` output.
|
|
45
|
+
|
|
46
|
+
## Scanner
|
|
47
|
+
|
|
48
|
+
`vp-tools scan-skills` traverses the following adapter directories:
|
|
49
|
+
|
|
50
|
+
| Adapter | Skill directory |
|
|
51
|
+
|---------|----------------|
|
|
52
|
+
| Claude Code | `~/.claude/skills/` |
|
|
53
|
+
| Cursor | `~/.cursor/skills/` |
|
|
54
|
+
| Codex | `~/.codex/skills/` |
|
|
55
|
+
| Antigravity | `~/.gemini/antigravity/skills/` |
|
|
56
|
+
| GitHub Copilot | `~/.config/gh-copilot/skills/` |
|
|
57
|
+
|
|
58
|
+
Adapter directories that do not exist are silently skipped. The same skill found in multiple adapter directories is merged into a single registry entry with all adapters listed.
|
|
59
|
+
|
|
60
|
+
## Registry Format
|
|
61
|
+
|
|
62
|
+
The registry is written to `~/.viepilot/skill-registry.json`:
|
|
63
|
+
|
|
64
|
+
```json
|
|
65
|
+
{
|
|
66
|
+
"version": "1.0",
|
|
67
|
+
"last_scan": "2026-04-20T10:30:00.000Z",
|
|
68
|
+
"scan_paths": [
|
|
69
|
+
"/Users/you/.claude/skills",
|
|
70
|
+
"/Users/you/.cursor/skills"
|
|
71
|
+
],
|
|
72
|
+
"skills": [
|
|
73
|
+
{
|
|
74
|
+
"id": "frontend-design",
|
|
75
|
+
"name": "frontend-design",
|
|
76
|
+
"source": null,
|
|
77
|
+
"version": null,
|
|
78
|
+
"description": "Opinionated frontend design guidance for UI-Direction sessions.",
|
|
79
|
+
"capabilities": ["ui-generation", "component-design", "responsive-layout"],
|
|
80
|
+
"tags": ["ui", "design", "frontend", "css"],
|
|
81
|
+
"best_practices": [
|
|
82
|
+
"Mobile-first: design breakpoints from 320px up",
|
|
83
|
+
"Use design tokens for consistency"
|
|
84
|
+
],
|
|
85
|
+
"adapters": ["claude-code", "cursor"],
|
|
86
|
+
"installed_paths": {
|
|
87
|
+
"claude-code": "/Users/you/.claude/skills/frontend-design",
|
|
88
|
+
"cursor": "/Users/you/.cursor/skills/frontend-design"
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
]
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Schema reference
|
|
96
|
+
|
|
97
|
+
| Field | Type | Description |
|
|
98
|
+
|-------|------|-------------|
|
|
99
|
+
| `id` | string | Directory name (unique per skill) |
|
|
100
|
+
| `name` | string | Display name (defaults to `id`) |
|
|
101
|
+
| `source` | string \| null | Installation source: `npm:pkg`, `github:org/repo`, `./path`, or `null` for manually placed skills |
|
|
102
|
+
| `version` | string \| null | Version from `skill-meta.json` (future); `null` for legacy skills |
|
|
103
|
+
| `description` | string | First non-heading paragraph from `SKILL.md` |
|
|
104
|
+
| `capabilities` | string[] | From `## Capabilities` section |
|
|
105
|
+
| `tags` | string[] | From `## Tags` section |
|
|
106
|
+
| `best_practices` | string[] | From `## Best Practices` section |
|
|
107
|
+
| `adapters` | string[] | Adapter IDs where this skill is installed |
|
|
108
|
+
| `installed_paths` | object | `{ adapterId: absolutePath }` |
|
|
109
|
+
|
|
110
|
+
## Workflow Integration
|
|
111
|
+
|
|
112
|
+
The registry is used automatically by ViePilot workflows:
|
|
113
|
+
|
|
114
|
+
### Brainstorm (UI-Direction)
|
|
115
|
+
When UI signals are detected during a brainstorm session, relevant skills (matched by `capabilities`) are silently applied — their `best_practices` are included in HTML generation without prompting. Matched skills are recorded in `notes.md` under `## skills_used`.
|
|
116
|
+
|
|
117
|
+
### Crystallize (skill decision lock)
|
|
118
|
+
After the brainstorm scope is locked, crystallize presents the skills used and asks the user to confirm which are required vs optional per phase. The decision is written to `PROJECT-CONTEXT.md` under `## Skills`.
|
|
119
|
+
|
|
120
|
+
### vp-auto (silent execution)
|
|
121
|
+
vp-auto reads `## Skills` from `PROJECT-CONTEXT.md` and injects skill best practices per task — no re-asking. Decisions made at crystallize time are final.
|
|
122
|
+
|
|
123
|
+
## Refreshing the Registry
|
|
124
|
+
|
|
125
|
+
Run `vp-tools scan-skills` any time you install a new skill manually or after `vp-tools install-skill` (which runs it automatically). The registry is not auto-refreshed on session start.
|
|
@@ -6,10 +6,10 @@ const fs = require('fs');
|
|
|
6
6
|
module.exports = {
|
|
7
7
|
id: 'antigravity',
|
|
8
8
|
name: 'Antigravity',
|
|
9
|
-
skillsDir: (home) => path.join(home, '.antigravity', 'skills'),
|
|
10
|
-
viepilotDir: (home) => path.join(home, '.antigravity', 'viepilot'),
|
|
9
|
+
skillsDir: (home) => path.join(home, '.gemini', 'antigravity', 'skills'),
|
|
10
|
+
viepilotDir: (home) => path.join(home, '.gemini', 'antigravity', 'viepilot'),
|
|
11
11
|
// {envToolDir} in SKILL.md files resolves to this value at install time (ENH-035)
|
|
12
|
-
executionContextBase: '.antigravity/viepilot',
|
|
12
|
+
executionContextBase: '.gemini/antigravity/viepilot',
|
|
13
13
|
// Post-install hint shown in "Next actions" after viepilot install
|
|
14
14
|
postInstallHint: 'Open project and run /vp-status',
|
|
15
15
|
hooks: {
|
|
@@ -29,6 +29,7 @@ module.exports = {
|
|
|
29
29
|
],
|
|
30
30
|
isAvailable: (home) => {
|
|
31
31
|
const h = home || os.homedir();
|
|
32
|
-
return fs.existsSync(path.join(h, '.antigravity'))
|
|
32
|
+
return fs.existsSync(path.join(h, '.gemini', 'antigravity'))
|
|
33
|
+
|| fs.existsSync(path.join(h, '.antigravity'));
|
|
33
34
|
}
|
|
34
35
|
};
|