viepilot 2.41.0 → 2.45.3

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 (40) hide show
  1. package/CHANGELOG.md +104 -0
  2. package/bin/viepilot.cjs +32 -0
  3. package/bin/vp-tools.cjs +95 -0
  4. package/docs/brainstorm/session-2026-04-24.md +131 -0
  5. package/docs/brainstorm/session-2026-04-25.md +109 -0
  6. package/lib/domain-packs/ai-product.json +33 -0
  7. package/lib/domain-packs/data-science.json +33 -0
  8. package/lib/domain-packs/devops.json +33 -0
  9. package/lib/domain-packs/mobile.json +33 -0
  10. package/lib/domain-packs/web-saas.json +33 -0
  11. package/lib/viepilot-calibrate.cjs +279 -0
  12. package/lib/viepilot-install.cjs +5 -3
  13. package/lib/viepilot-persona.cjs +446 -0
  14. package/package.json +1 -1
  15. package/skills/vp-audit/SKILL.md +10 -0
  16. package/skills/vp-auto/SKILL.md +10 -0
  17. package/skills/vp-brainstorm/SKILL.md +16 -1
  18. package/skills/vp-crystallize/SKILL.md +10 -0
  19. package/skills/vp-debug/SKILL.md +10 -0
  20. package/skills/vp-design/SKILL.md +219 -0
  21. package/skills/vp-docs/SKILL.md +10 -0
  22. package/skills/vp-evolve/SKILL.md +10 -0
  23. package/skills/vp-info/SKILL.md +10 -0
  24. package/skills/vp-pause/SKILL.md +10 -0
  25. package/skills/vp-persona/SKILL.md +207 -0
  26. package/skills/vp-proposal/SKILL.md +10 -0
  27. package/skills/vp-request/SKILL.md +10 -0
  28. package/skills/vp-resume/SKILL.md +10 -0
  29. package/skills/vp-rollback/SKILL.md +34 -1
  30. package/skills/vp-skills/SKILL.md +10 -0
  31. package/skills/vp-status/SKILL.md +10 -0
  32. package/skills/vp-task/SKILL.md +10 -0
  33. package/skills/vp-ui-components/SKILL.md +10 -0
  34. package/skills/vp-update/SKILL.md +10 -0
  35. package/workflows/autonomous.md +59 -0
  36. package/workflows/brainstorm.md +148 -1
  37. package/workflows/crystallize.md +111 -0
  38. package/workflows/design.md +601 -0
  39. package/workflows/evolve.md +9 -0
  40. package/workflows/rollback.md +79 -10
package/CHANGELOG.md CHANGED
@@ -7,6 +7,110 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.45.3] - 2026-04-25
11
+
12
+ ### Fixed
13
+ - **BUG-024**: `viepilot-install.cjs` hard-coded `libFiles` list caused `viepilot-persona.cjs`,
14
+ `skill-registry.cjs`, `skill-installer.cjs`, and `lib/adapters/`, `lib/hooks/`,
15
+ `lib/domain-packs/` subdirectories to be absent from all installed instances
16
+ (`~/.claude/viepilot/lib/`, `~/.cursor/viepilot/lib/`, Windows equivalents).
17
+ Fix: replaced explicit list with dynamic `lib/` directory scan — all files and
18
+ subdirectories now copied automatically. Affected: `persona auto-switch/context`,
19
+ `scan-skills`, `install-skill`, `uninstall-skill`, adapter detection (BUG-024)
20
+
21
+ ## [2.45.2] - 2026-04-25
22
+
23
+ ### Enhanced
24
+ - **ENH-077**: crystallize Step 1D.14 now offers AUQ post-export handoff —
25
+ after design.md exports to project root, prompts "Sync tokens to stylesheets via
26
+ /vp-design --sync?" with Run now / Skip options; silent skip when no stylesheet
27
+ target detected (tailwind.config.js / .css / .scss absent) (ENH-077)
28
+
29
+ ## [2.45.1] - 2026-04-25
30
+
31
+ ### Enhanced
32
+ - **ENH-076.5**: Architect workspace adds `design.html` page when design.md or design tokens
33
+ are present — visual color swatches grid, typography scale table, spacing grid, border-radius
34
+ samples, component token table; bidirectional sync with notes.md `## design_tokens`;
35
+ hub nav link added to `index.html` (ENH-076)
36
+
37
+ ## [2.45.0] - 2026-04-25
38
+
39
+ ### Added
40
+ - **ENH-076.4**: New skill `vp-design` — manage Design.MD design system files:
41
+ `--init` (Q&A from scratch or awesome-design-md import from 55+ brands),
42
+ `--sync` (tokens → Tailwind / CSS custom properties / SCSS auto-detected),
43
+ `--audit` (compliance report with ❌/⚠️/✅ severity levels),
44
+ `--import [brand]` (community template picker with Apply/Customize/Reference modes) (ENH-076)
45
+
46
+ ## [2.44.1] - 2026-04-25
47
+
48
+ ### Enhanced
49
+ - **ENH-076.3**: vp-auto Preflight 5.5 — Design.MD TOKEN_MAP injection for UI tasks:
50
+ Level 1 silent context injection, Level 2 checklist items (UI ACs), Level 3 post-task
51
+ audit with auto-fix; backend-only tasks skip injection; monorepo nearest-file rule (ENH-076)
52
+
53
+ ## [2.44.0] - 2026-04-25
54
+
55
+ ### Enhanced
56
+ - **ENH-076.1**: vp-brainstorm `--ui` mode now auto-extracts design tokens → generates
57
+ `design.md` (Design.MD v1 spec) in session directory alongside `index.html`; `notes.md`
58
+ gets `## design_tokens` YAML section with `design_md_path` pointer (ENH-076)
59
+ - **ENH-076.2**: vp-crystallize Step 1D.14 — mandatory-acknowledge gate for design.md:
60
+ export to project root + `ARCHITECTURE.md ## Design System` + `PROJECT-CONTEXT.md` flag;
61
+ idempotent skip writes `design_md_status: skipped`; conflict handling: Override/Merge/Keep/Diff (ENH-076)
62
+
63
+ ## [2.43.2] - 2026-04-25
64
+
65
+ ### Fixed
66
+ - **BUG-023**: vp-brainstorm session-transition/next-steps prompt ("What would you like to
67
+ do next?" — crystallize / update UI artifacts / continue discussing) now uses
68
+ `AskUserQuestion` on Claude Code terminal; `workflows/brainstorm.md` +
69
+ `skills/vp-brainstorm/SKILL.md` updated (distinct from BUG-022 Q&A content choices)
70
+
71
+ ## [2.43.1] - 2026-04-24
72
+
73
+ ### Fixed
74
+ - **vp-brainstorm**: mid-session structured decision questions now use `AskUserQuestion`
75
+ on Claude Code terminal when ≥2 discrete named options are available; free-form
76
+ open questions remain conversational plain text; SKILL.md "Prompts using AUQ" list
77
+ updated (BUG-022)
78
+
79
+ ## [2.43.0] - 2026-04-24
80
+
81
+ ### Enhanced
82
+ - **vp-rollback**: AUQ checkpoint selection with pagination — structured `AskUserQuestion`
83
+ prompt replaces plain-text table; "Show N more →" option pages through older checkpoints;
84
+ `--limit N` flag controls page size (default: 10); `--list` flag unchanged; ENH-059
85
+ ToolSearch preload applied; text fallback on non-Claude Code adapters (ENH-075)
86
+
87
+ ## [2.42.0] - 2026-04-24
88
+
89
+ ### Added
90
+ - **ENH-073**: vp-persona — fully automated cross-project persona system (no wizard)
91
+ - `lib/viepilot-persona.cjs`: `inferPersona()` detects domain from project files + git shortlog (no setup required)
92
+ - Auto-switch persona on `$PWD` change; auto-merge when 2+ domain signals detected in same project
93
+ - `team_size` inferred from `git shortlog -sn`; `output_style` defaults lean, self-learned from calibration traces
94
+ - 3-layer resolution: project-override > context-map > global active persona
95
+ - `lib/viepilot-calibrate.cjs`: always-on adaptive calibration via Reflexion pattern
96
+ - Session traces written async to `~/.viepilot/traces/` after every session
97
+ - 🟢 low-risk changes (topic_skip, stack_add) auto-applied silently
98
+ - 🟡 medium-risk changes (output_style, phase_default) auto-applied + logged to `pending-review.md`
99
+ - 🔴 high-risk changes blocked (caller decides to prompt, max once per session)
100
+ - `guardrail_journal` prevents re-proposing rejected patterns
101
+ - JSON Patch RFC 6902 workflow overlays — base workflows never modified
102
+ - 5 built-in domain packs: `web-saas`, `data-science`, `mobile`, `devops`, `ai-product`
103
+ - Each: `topic_priority`, `extra_topics` with Q&A, `phase_template`, `architect_pages`, `stacks_hint`
104
+ - `vp-tools persona` subcommand: `get`/`infer`/`list`/`set`/`auto-switch`/`context`
105
+ - `skills/vp-persona/SKILL.md`: new skill for persona inspection and optional correction (`--refine`)
106
+ - `<persona_context>` block injected into all 19 `vp-*` SKILL.md files (including vp-persona itself)
107
+ - `workflows/brainstorm.md`: domain pack topic injection (Step 0B)
108
+ - `workflows/autonomous.md`: persona context injected per task
109
+ - `workflows/crystallize.md`: `output_style` adaptation (lean/balanced/enterprise)
110
+ - `workflows/evolve.md`: `phase_template` suggestion from domain pack
111
+ - `bin/viepilot.cjs`: `install-domain <pack-name>` subcommand for community packs
112
+ - 35 unit tests (phase108); full suite: 1618 tests pass
113
+
10
114
  ## [2.41.0] - 2026-04-24
11
115
 
12
116
  ### Added
package/bin/viepilot.cjs CHANGED
@@ -567,6 +567,38 @@ async function main() {
567
567
  }
568
568
  }
569
569
 
570
+ if (command === 'install-domain') {
571
+ const packName = rest[0];
572
+ if (!packName) {
573
+ console.error('Usage: viepilot install-domain <pack-name>');
574
+ console.error('Example: viepilot install-domain fintech');
575
+ process.exit(1);
576
+ }
577
+ const npmPkg = `viepilot-domain-${packName}`;
578
+ const { execSync } = require('child_process');
579
+ const path = require('path');
580
+ const fs = require('fs');
581
+ try {
582
+ console.log(`Installing ${npmPkg}...`);
583
+ execSync(`npm install ${npmPkg}`, { stdio: 'inherit' });
584
+ // Copy domain-pack.json from installed package to lib/domain-packs/
585
+ const pkgRoot = path.dirname(require.resolve(`${npmPkg}/package.json`));
586
+ const packFile = path.join(pkgRoot, 'domain-pack.json');
587
+ if (fs.existsSync(packFile)) {
588
+ const dest = path.join(__dirname, '..', 'lib', 'domain-packs', `${packName}.json`);
589
+ fs.mkdirSync(path.dirname(dest), { recursive: true });
590
+ fs.copyFileSync(packFile, dest);
591
+ console.log(`Domain pack '${packName}' installed → lib/domain-packs/${packName}.json`);
592
+ } else {
593
+ console.warn(`Installed ${npmPkg} but no domain-pack.json found.`);
594
+ }
595
+ process.exit(0);
596
+ } catch (err) {
597
+ console.error(`Failed to install ${npmPkg}: ${err.message}`);
598
+ process.exit(1);
599
+ }
600
+ }
601
+
570
602
  if (command !== 'install' && command !== 'uninstall') {
571
603
  console.error(`Unknown command: ${command}`);
572
604
  printHelp();
package/bin/vp-tools.cjs CHANGED
@@ -1203,6 +1203,80 @@ ${colors.cyan}Examples:${colors.reset}
1203
1203
  });
1204
1204
  },
1205
1205
 
1206
+ /**
1207
+ * ENH-073: Manage cross-project personas.
1208
+ * persona get → print active persona JSON
1209
+ * persona infer [dir] → run inferPersona, print result, update context-map
1210
+ * persona list → list all ~/.viepilot/personas/*.json
1211
+ * persona set <name> → set active persona by name
1212
+ * persona auto-switch → auto-detect and switch for cwd (called at skill start)
1213
+ * persona context [dir] → print persona-context.md content
1214
+ */
1215
+ 'persona': (args) => {
1216
+ const {
1217
+ inferPersona, resolvePersona, generatePersonaContext,
1218
+ readActivePersona, writePersona, setActivePersona, listPersonas,
1219
+ updateContextMap, autoSwitch,
1220
+ } = require('../lib/viepilot-persona.cjs');
1221
+
1222
+ const op = args[0] || 'get';
1223
+ const dir = args[1] ? require('path').resolve(args[1]) : process.cwd();
1224
+
1225
+ if (op === 'get') {
1226
+ const persona = readActivePersona();
1227
+ if (!persona) { process.stdout.write('No active persona\n'); process.exit(0); }
1228
+ process.stdout.write(JSON.stringify(persona, null, 2) + '\n');
1229
+ process.exit(0);
1230
+ }
1231
+
1232
+ if (op === 'list') {
1233
+ const personas = listPersonas();
1234
+ if (!personas.length) { process.stdout.write('No personas saved\n'); process.exit(0); }
1235
+ for (const p of personas) {
1236
+ const marker = p.active ? '[active] ' : ' ';
1237
+ process.stdout.write(`${marker}${p.name} domain:${p.domain} confidence:${p.confidence}\n`);
1238
+ }
1239
+ process.exit(0);
1240
+ }
1241
+
1242
+ if (op === 'set') {
1243
+ const name = args[1];
1244
+ if (!name) { process.stderr.write('Usage: persona set <name>\n'); process.exit(1); }
1245
+ setActivePersona(name);
1246
+ process.stdout.write(`Active persona set to: ${name}\n`);
1247
+ process.exit(0);
1248
+ }
1249
+
1250
+ if (op === 'infer') {
1251
+ inferPersona(dir).then(persona => {
1252
+ writePersona(persona.name, persona);
1253
+ setActivePersona(persona.name);
1254
+ updateContextMap(dir, persona.name);
1255
+ process.stdout.write(JSON.stringify(persona, null, 2) + '\n');
1256
+ process.exit(0);
1257
+ }).catch(() => process.exit(0));
1258
+ return;
1259
+ }
1260
+
1261
+ if (op === 'auto-switch') {
1262
+ autoSwitch(dir).then(() => process.exit(0)).catch(() => process.exit(0));
1263
+ return;
1264
+ }
1265
+
1266
+ if (op === 'context') {
1267
+ (async () => {
1268
+ let persona = resolvePersona(dir);
1269
+ if (!persona) persona = await inferPersona(dir);
1270
+ process.stdout.write(generatePersonaContext(persona) + '\n');
1271
+ process.exit(0);
1272
+ })().catch(() => process.exit(0));
1273
+ return;
1274
+ }
1275
+
1276
+ process.stderr.write(`Unknown persona op: ${op}\nUsage: persona get|infer|list|set|auto-switch|context\n`);
1277
+ process.exit(1);
1278
+ },
1279
+
1206
1280
  /**
1207
1281
  * Scan installed skills and rebuild ~/.viepilot/skill-registry.json (BUG-019)
1208
1282
  */
@@ -1330,6 +1404,26 @@ ${colors.cyan}Examples:${colors.reset}
1330
1404
  'vp-tools check-update --force',
1331
1405
  ],
1332
1406
  },
1407
+ 'persona': {
1408
+ usage: 'vp-tools persona <op> [dir]',
1409
+ description: 'Manage cross-project personas (ENH-073)',
1410
+ options: [
1411
+ 'get Show active persona JSON',
1412
+ 'infer [dir] Infer persona from project files + git',
1413
+ 'list List all saved personas',
1414
+ 'set <name> Set active persona by name',
1415
+ 'auto-switch Auto-detect and switch persona for current directory',
1416
+ 'context [dir] Print persona-context.md content for current project',
1417
+ ],
1418
+ examples: [
1419
+ 'vp-tools persona get',
1420
+ 'vp-tools persona infer .',
1421
+ 'vp-tools persona list',
1422
+ 'vp-tools persona set auto-web-saas',
1423
+ 'vp-tools persona auto-switch',
1424
+ 'vp-tools persona context',
1425
+ ],
1426
+ },
1333
1427
  update: {
1334
1428
  usage: 'vp-tools update [--dry-run] [--yes] [--global]',
1335
1429
  description: 'Update viepilot to npm latest (local dependency, global install, or explicit --global)',
@@ -1391,6 +1485,7 @@ ${colors.cyan}Commands:${colors.reset}
1391
1485
  ${colors.bold}get-registry${colors.reset} [--id <id>] Output global skill registry as JSON
1392
1486
  ${colors.bold}scan-skills${colors.reset} Scan installed skills → ~/.viepilot/skill-registry.json
1393
1487
  ${colors.bold}check-update${colors.reset} [--silent] Check for latest ViePilot version on npm (24h cached)
1488
+ ${colors.bold}persona${colors.reset} <op> Manage user personas (get|infer|list|set|auto-switch|context)
1394
1489
  ${colors.bold}help${colors.reset} [command] Show help (optionally for specific command)
1395
1490
 
1396
1491
  ${colors.cyan}Examples:${colors.reset}
@@ -0,0 +1,131 @@
1
+ # Brainstorm Session — 2026-04-24
2
+
3
+ ## Session Info
4
+ - **Date**: 2026-04-24
5
+ - **Topic**: vp-persona — ViePilot Workflow Customization Skill
6
+ - **Status**: Completed
7
+ - **workflow_version**: 2.41.0
8
+
9
+ ## Core Idea
10
+
11
+ A new skill `/vp-persona` that creates a **user-level, cross-project identity** for ViePilot.
12
+ Lets users customize ALL ViePilot workflows to fit their domain, profession, and interests —
13
+ without re-declaring context per project.
14
+
15
+ ## Problem Statement
16
+
17
+ ViePilot is currently a general-purpose framework. Multi-domain professionals ("kiêm nhiệm")
18
+ working across Web SaaS, Embedded, Data Science, Mobile face:
19
+ - Brainstorm topics irrelevant to their domain
20
+ - Wrong phase templates
21
+ - No cross-project user identity
22
+ - Must re-declare stack/context for every project
23
+
24
+ ## Key Design Decisions
25
+
26
+ ### 1. Multi-Persona architecture (not single profile)
27
+ - `~/.viepilot/personas/` — named persona files
28
+ - `~/.viepilot/persona.json` — active persona pointer
29
+ - `~/.viepilot/context-map.json` — directory → persona bindings
30
+
31
+ ### 2. Layered resolution (3 layers)
32
+ ```
33
+ Priority: project > session > global
34
+ 1. .viepilot/persona-override.json ← per-project explicit
35
+ 2. context-map.json pattern match ← directory-based auto
36
+ 3. ~/.viepilot/persona.json (active) ← global default
37
+ ```
38
+
39
+ ### 3. Switch + Merge both supported
40
+ - **Switch**: bind project dir to a named persona, change with 1 command
41
+ - **Merge**: create hybrid persona from multiple domains (e.g. IoT Full-stack = web-saas + embedded-iot)
42
+ - Analogy: git branch (switch) + git merge (merge)
43
+
44
+ ### 4. Auto-detection from project files
45
+ | Signal file | Detected domain |
46
+ |------------|-----------------|
47
+ | `package.json` + `prisma/` | web-saas |
48
+ | `CMakeLists.txt` + `sdkconfig` | embedded |
49
+ | `requirements.txt` + `notebooks/` | data-science |
50
+ | `pubspec.yaml` / `*.xcodeproj` | mobile |
51
+ | `Dockerfile` + `terraform/` | devops |
52
+ | `pyproject.toml` + `langchain` | ai-product |
53
+
54
+ ### 5. Persona schema
55
+ ```json
56
+ {
57
+ "name": "Web SaaS Dev",
58
+ "domain": "web-saas",
59
+ "role": "full-stack",
60
+ "stacks": ["nextjs", "nestjs", "postgresql"],
61
+ "team_size": "solo",
62
+ "output_style": "lean",
63
+ "brainstorm": {
64
+ "topic_priority": ["auth", "user-data", "api", "admin"],
65
+ "topic_skip": ["embedded", "content-mgmt"]
66
+ },
67
+ "phase_template": "lean-startup",
68
+ "interests": ["ai-integration", "saas", "startup"]
69
+ }
70
+ ```
71
+
72
+ ### 6. Domain Packs (5 built-in + community)
73
+ | Pack | Extra topics | Phase template | Extra architect pages |
74
+ |------|-------------|----------------|----------------------|
75
+ | `web-saas` | Billing, Multi-tenant, Onboarding | Auth→Core→Monetize→Scale | billing.html, tenant.html |
76
+ | `data-science` | Dataset mgmt, Model versioning, Drift monitoring | Data→EDA→Train→Serve→Monitor | ml-pipeline.html |
77
+ | `mobile` | Push, Offline sync, Store submit | Auth→Core→Offline→Submit | mobile-flow.html |
78
+ | `devops` | IaC, CI/CD, SLO, Incident | Infra→CI/CD→Observe→Runbooks | infra-topology.html |
79
+ | `ai-product` | LLM integration, RAG, Eval/feedback | Wrapper→Prompt→RAG→Eval→UX | llm-arch.html |
80
+
81
+ ### 7. vp-persona commands
82
+ ```
83
+ /vp-persona → Show active persona
84
+ /vp-persona --create web-saas → Create new persona (wizard)
85
+ /vp-persona --switch embedded → Switch active persona
86
+ /vp-persona --list → List all personas
87
+ /vp-persona --bind . web-saas → Bind current dir to persona
88
+ /vp-persona --auto → Enable auto-detect
89
+ /vp-persona --merge web embedded → Create hybrid persona
90
+ /vp-persona --export / --import → Backup/share personas
91
+ ```
92
+
93
+ ### 8. Workflow adaptations when persona active
94
+ - **vp-brainstorm**: topic order reordered by priority; skipped topics hidden; domain pack topics injected
95
+ - **vp-auto**: stack preflight uses persona stacks automatically; persona-context.md injected per task
96
+ - **vp-crystallize**: output_style "lean" → shorter docs; "enterprise" → full docs + compliance
97
+ - **vp-evolve**: new phase suggestions follow persona's phase_template
98
+
99
+ ## Phases
100
+
101
+ ### Phase 1 — Foundation
102
+ - `vp-persona` skill + wizard (5-question Q&A)
103
+ - `~/.viepilot/personas/` multi-file support
104
+ - `persona-context.md` injection into all skills
105
+
106
+ ### Phase 2 — Multi-context
107
+ - `context-map.json` + directory binding (`--bind`)
108
+ - Auto-detection from project files
109
+ - Session-start smart prompt for multi-domain users
110
+
111
+ ### Phase 3 — Domain Packs
112
+ - 5 built-in domain packs (web-saas, data-science, mobile, devops, ai-product)
113
+ - Domain pack schema + community extensibility (npm install viepilot-domain-*)
114
+
115
+ ### Phase 4 — Merge + Advanced
116
+ - `/vp-persona --merge` hybrid personas
117
+ - Interest-based proactive hints in brainstorm
118
+ - Per-project `persona-override.json`
119
+
120
+ ## Open Questions
121
+ - Should domain packs be separate npm packages or bundled?
122
+ - How to handle conflicts when merge produces duplicate topics?
123
+ - Should `persona-context.md` be injected as a system-prompt prefix or as a workflow step?
124
+
125
+ ## Project meta intake (FEAT-009)
126
+ - Profile binding: skipped (this is ViePilot framework repo itself)
127
+
128
+ ## Background extracted ideas
129
+ - Interest-based proactive suggestions (e.g. "ai-integration" interest → proactive LLM arch hints)
130
+ - Community domain pack registry (viepilot-domain-fintech, viepilot-domain-healthcare...)
131
+ - Persona export/import for team sharing (onboard new dev with same persona)
@@ -0,0 +1,109 @@
1
+ # Brainstorm Session — 2026-04-25
2
+
3
+ ## Meta
4
+ - **Session ID**: session-2026-04-25
5
+ - **Topic**: Design.MD × ViePilot Integration (ENH-076)
6
+ - **Status**: Completed
7
+ - **workflow_version**: 2.43.2
8
+ - **Participants**: User + AI
9
+
10
+ ## Summary
11
+ Research session trên tiêu chuẩn Design.MD (Google Labs, April 2026) và brainstorm
12
+ cách tích hợp nó toàn diện vào ViePilot workflow — từ brainstorm → crystallize → auto.
13
+
14
+ ## Research: Design.MD Standard
15
+
16
+ Design.MD là file specification từ Google Labs (21/04/2026, Apache 2.0) — Markdown + YAML
17
+ front matter mô tả visual design system để AI coding agents hiểu brand identity.
18
+
19
+ - **Creator**: Google Labs / Google Stitch 2.0
20
+ - **Format**: YAML front matter (tokens) + Markdown sections (rationale)
21
+ - **Adopted by**: Claude Code, Cursor, Windsurf, Kiro
22
+ - **Community**: awesome-design-md — 55+ brand examples
23
+
24
+ ### Standard sections
25
+ - `colors`: semantic palette (primary, surface, accent, error, success, warning)
26
+ - `typography`: fontFamily, fontSize, fontWeight, lineHeight
27
+ - `spacing`: base unit + scale
28
+ - `rounded`: corner radius tokens
29
+ - `components`: component-specific tokens
30
+
31
+ ---
32
+
33
+ ## Decisions
34
+
35
+ ### D1: Scope — 5 integration points across ViePilot
36
+ 1. **vp-brainstorm**: auto-extract design tokens → generate design.md in session dir
37
+ 2. **vp-crystallize**: mandatory-acknowledge gate + export to project root
38
+ 3. **vp-auto**: preflight reads design.md, injects TOKEN_MAP into UI tasks
39
+ 4. **new skill vp-design**: init/sync/audit/import commands
40
+ 5. **Architect workspace**: design.html visual page
41
+
42
+ ### D2: vp-brainstorm token extraction
43
+ - Triggered when `--ui` flag OR ≥2 design keywords detected
44
+ - tokens extracted to `notes.md ## design_tokens` YAML section
45
+ - design.md written to `.viepilot/ui-direction/{session-id}/design.md`
46
+
47
+ ### D3: vp-crystallize gate — mandatory-acknowledge (not hard block)
48
+ - Trigger: design.md exists OR design_tokens in notes.md OR ≥3 design keywords
49
+ - AUQ with 3 options: Export (recommended) / Finalize & export / Skip with note
50
+ - Skip writes `design_md_status: skipped` (idempotent — won't re-ask same session)
51
+ - Export path: Step 1D.14 — after existing coverage exports
52
+ - Output: project root design.md + ARCHITECTURE.md ## Design System + PROJECT-CONTEXT.md flag
53
+
54
+ ### D4: vp-auto — 3 injection levels
55
+ - Level 1: Silent context injection (always for UI tasks)
56
+ - Level 2: Checklist items (when task has explicit UI acceptance criteria)
57
+ - Level 3: Post-task compliance audit (when task output is HTML file)
58
+ - UI keyword detection: html/css/style/component/tailwind/layout/button/card/form/page etc.
59
+ - Edge cases: backend-only tasks skip, monorepo nearest-design.md wins
60
+
61
+ ### D5: vp-design skill commands
62
+ - `--init`: Q&A from scratch OR import from awesome-design-md (55+ brands)
63
+ - `--sync`: tokens → Tailwind config / CSS variables / SCSS
64
+ - `--audit`: scan implementation vs spec, report deviations
65
+ - `--import [brand]`: fetch community template (Linear, Notion, Stripe...)
66
+
67
+ ### D6: ARCHITECTURE.md Design System section format
68
+ - Token summary table (colors/typography/spacing/rounded)
69
+ - Design principles from design.md ## Overview
70
+ - Reference to design.md at project root
71
+
72
+ ---
73
+
74
+ ## Open Questions
75
+
76
+ - Q1: Should design.md be committed to git by default? (Yes — it's a project artifact like ARCHITECTURE.md)
77
+ - Q2: For vp-design --sync with Tailwind: CSS custom properties or direct tailwind.config.js extension?
78
+ → Probably both, detected by project structure
79
+ - Q3: awesome-design-md catalog integration — fetch at runtime vs. bundle with ViePilot?
80
+ → Fetch at runtime (keep ViePilot lean)
81
+
82
+ ---
83
+
84
+ ## Phases
85
+
86
+ ### Phase 1 (ENH-076 core)
87
+ - 76.1: vp-brainstorm design token extraction + design.md generation
88
+ - 76.2: vp-crystallize Step 1D.14 mandatory gate + export pipeline
89
+ - 76.3: vp-auto preflight 5.5 + TOKEN_MAP injection + post-task audit
90
+ - 76.4: new skill vp-design (SKILL.md + workflows/design.md)
91
+ - 76.5: Architect workspace design.html page
92
+
93
+ ### Phase 2 (polish)
94
+ - 76.6: awesome-design-md runtime catalog integration
95
+ - 76.7: vp-design --sync multi-target (Tailwind + CSS vars + SCSS)
96
+ - 76.8: vp-design --audit full HTML/CSS scan
97
+
98
+ ---
99
+
100
+ ## Action Items
101
+ - [ ] Log ENH-076 via /vp-request
102
+ - [ ] Plan phases via /vp-evolve
103
+ - [ ] Execute via /vp-auto
104
+
105
+ ---
106
+
107
+ ## Project Meta Intake (FEAT-009)
108
+ - Profile already bound — skip intake.
109
+
@@ -0,0 +1,33 @@
1
+ {
2
+ "id": "ai-product",
3
+ "label": "AI Product / LLM Application",
4
+ "topic_priority": ["llm-integration", "rag-pipeline", "prompt-mgmt", "eval", "ux", "guardrails"],
5
+ "extra_topics": [
6
+ {
7
+ "id": "llm-integration",
8
+ "label": "LLM Integration",
9
+ "questions": ["LLM provider (OpenAI/Anthropic/Gemini/local)?", "Model selection strategy (cost vs quality)?", "Streaming vs batch response?", "Fallback chain if primary model fails?"]
10
+ },
11
+ {
12
+ "id": "rag-pipeline",
13
+ "label": "RAG Pipeline",
14
+ "questions": ["Document ingestion format (PDF/HTML/Markdown)?", "Chunking strategy (fixed/semantic/hierarchical)?", "Vector DB (Pinecone/Qdrant/pgvector/Chroma)?", "Embedding model?", "Retrieval method (semantic/hybrid/BM25)?"]
15
+ },
16
+ {
17
+ "id": "prompt-mgmt",
18
+ "label": "Prompt Management",
19
+ "questions": ["Prompt versioning strategy?", "Prompt storage (DB/Git/Langfuse)?", "System prompt vs user prompt separation?", "Prompt injection protection?"]
20
+ },
21
+ {
22
+ "id": "eval-feedback",
23
+ "label": "Eval & Feedback Loop",
24
+ "questions": ["Eval framework (RAGAS/DeepEval/custom)?", "Human feedback collection (thumbs up/down/rubric)?", "Evals in CI/CD pipeline?", "Latency + cost tracking per request?"]
25
+ }
26
+ ],
27
+ "phase_template": {
28
+ "name": "ai-product",
29
+ "phases": ["LLM Wrapper & Auth", "Prompt Engineering & RAG", "Eval Pipeline", "UX & Feedback Loop", "Guardrails & Cost Control"]
30
+ },
31
+ "architect_pages": ["llm-arch.html", "rag-flow.html"],
32
+ "stacks_hint": ["langchain", "openai", "anthropic", "pgvector", "fastapi", "nextjs", "redis"]
33
+ }
@@ -0,0 +1,33 @@
1
+ {
2
+ "id": "data-science",
3
+ "label": "Data Science / ML",
4
+ "topic_priority": ["dataset", "eda", "model-training", "evaluation", "serving", "monitoring"],
5
+ "extra_topics": [
6
+ {
7
+ "id": "dataset",
8
+ "label": "Dataset Management",
9
+ "questions": ["Data sources (structured/unstructured/streaming)?", "Data versioning strategy (DVC/Delta Lake/LakeFS)?", "PII/sensitive data handling?", "Train/val/test split strategy?"]
10
+ },
11
+ {
12
+ "id": "model-versioning",
13
+ "label": "Model Versioning",
14
+ "questions": ["Model registry (MLflow/W&B/SageMaker)?", "Experiment tracking metadata?", "Artifact storage (S3/GCS/local)?"]
15
+ },
16
+ {
17
+ "id": "drift-monitoring",
18
+ "label": "Drift & Quality Monitoring",
19
+ "questions": ["Data drift detection (Evidently/WhyLogs/custom)?", "Model performance degradation alerts?", "Retraining trigger strategy?"]
20
+ },
21
+ {
22
+ "id": "eval-pipeline",
23
+ "label": "Evaluation Pipeline",
24
+ "questions": ["Offline eval metrics (AUC/F1/BLEU/ROUGE)?", "Human eval process?", "A/B testing framework for model versions?"]
25
+ }
26
+ ],
27
+ "phase_template": {
28
+ "name": "ml-pipeline",
29
+ "phases": ["Data Ingestion & EDA", "Feature Engineering & Training", "Evaluation & Registry", "Serving & API", "Monitoring & Retraining"]
30
+ },
31
+ "architect_pages": ["ml-pipeline.html", "data-lineage.html"],
32
+ "stacks_hint": ["python", "pandas", "pytorch", "fastapi", "mlflow", "postgresql", "redis"]
33
+ }
@@ -0,0 +1,33 @@
1
+ {
2
+ "id": "devops",
3
+ "label": "DevOps / Platform Engineering",
4
+ "topic_priority": ["infra", "ci-cd", "observability", "slo", "incident-mgmt", "security"],
5
+ "extra_topics": [
6
+ {
7
+ "id": "iac",
8
+ "label": "Infrastructure as Code",
9
+ "questions": ["IaC tool (Terraform/Pulumi/CloudFormation/CDK)?", "Cloud provider (AWS/GCP/Azure/multi)?", "State backend (S3/GCS/Terraform Cloud)?", "Module/stack organization strategy?"]
10
+ },
11
+ {
12
+ "id": "ci-cd",
13
+ "label": "CI/CD Pipeline",
14
+ "questions": ["CI platform (GitHub Actions/GitLab CI/CircleCI/Jenkins)?", "Deploy strategy (blue-green/canary/rolling)?", "Secrets management (Vault/AWS SSM/GitHub Secrets)?", "PR-level preview environments?"]
15
+ },
16
+ {
17
+ "id": "slo-sla",
18
+ "label": "SLO / SLA",
19
+ "questions": ["Availability target (99.9%/99.99%)?", "Latency SLOs (p95/p99)?", "Error budget policy?", "SLO monitoring tool (Datadog/Prometheus/Grafana)?"]
20
+ },
21
+ {
22
+ "id": "incident-mgmt",
23
+ "label": "Incident Management",
24
+ "questions": ["On-call rotation tool (PagerDuty/OpsGenie/Rootly)?", "Runbook format and storage?", "Post-mortem process?", "Alert fatigue mitigation strategy?"]
25
+ }
26
+ ],
27
+ "phase_template": {
28
+ "name": "infra-ops",
29
+ "phases": ["Infrastructure Foundation", "CI/CD & Automation", "Observability & Alerting", "Runbooks & Incident Response"]
30
+ },
31
+ "architect_pages": ["infra-topology.html", "slo.html"],
32
+ "stacks_hint": ["terraform", "docker", "kubernetes", "prometheus", "grafana", "github-actions"]
33
+ }
@@ -0,0 +1,33 @@
1
+ {
2
+ "id": "mobile",
3
+ "label": "Mobile App",
4
+ "topic_priority": ["auth", "core-features", "offline-sync", "push-notifications", "app-store", "deep-links"],
5
+ "extra_topics": [
6
+ {
7
+ "id": "push-notifications",
8
+ "label": "Push Notifications",
9
+ "questions": ["Push provider (FCM/APNs/OneSignal/Expo)?", "Notification categories and opt-in flow?", "Deep link handling from notification tap?", "Background/foreground handling?"]
10
+ },
11
+ {
12
+ "id": "offline-sync",
13
+ "label": "Offline Sync",
14
+ "questions": ["Offline-first or online-required?", "Conflict resolution strategy (last-write-wins/CRDT/manual)?", "Local storage (SQLite/Realm/AsyncStorage/Core Data)?", "Sync trigger (background/explicit/realtime)?"]
15
+ },
16
+ {
17
+ "id": "app-store",
18
+ "label": "App Store Submission",
19
+ "questions": ["Target platforms (iOS/Android/both)?", "App review checklist (privacy policy, ATT prompt, entitlements)?", "CI/CD for store deployment (Fastlane/EAS/Bitrise)?"]
20
+ },
21
+ {
22
+ "id": "deep-links",
23
+ "label": "Deep Links & Universal Links",
24
+ "questions": ["URL scheme vs universal links?", "Deferred deep linking (install → open specific screen)?", "Attribution provider (Branch/AppsFlyer/Adjust)?"]
25
+ }
26
+ ],
27
+ "phase_template": {
28
+ "name": "mobile-launch",
29
+ "phases": ["Auth & Navigation", "Core Features", "Offline & Sync", "Store Submission & Launch"]
30
+ },
31
+ "architect_pages": ["mobile-flow.html", "push.html"],
32
+ "stacks_hint": ["react-native", "expo", "flutter", "firebase", "postgresql"]
33
+ }