create-vasvibe 1.1.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-vasvibe",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Scaffold a new project with VasVibe agents, prompts, and workflows preconfigured (Claude, OpenCode, GitHub Copilot).",
   "type": "module",
   "bin": {

package/src/index.mjs

@@ -7,6 +7,7 @@ import { runPrompts } from './prompts.mjs';
 import { scaffold } from './scaffold.mjs';
 import { initRepo } from './git.mjs';
 import { log, pathExists, isDirEmpty, isValidProjectName } from './utils.mjs';
+import { isVasvibeProject, runUpgrade } from './upgrade.mjs';
 import pc from 'picocolors';
 
 const HELP = `
@@ -14,29 +15,33 @@ ${pc.bold('create-vasvibe')} — scaffold a project with VasVibe agents preconfi
 
 ${pc.bold('Usage:')}
   npx create-vasvibe <project-name> [options]
+  npx create-vasvibe upgrade [path]         Upgrade agent files in an existing project
 
 ${pc.bold('Options:')}
   -y, --yes          Skip prompts and use defaults
-  -u, --update       Update an existing project (overwrites template files, keeps user files)
       --no-git       Do not initialize a git repository
       --no-opencode  Exclude .opencode/ (commands, skills)
       --no-claude    Exclude .claude/ and .agents/
       --no-github    Exclude .github/prompts/
       --no-workflows Exclude agent/workflows/
+      --depth=<level> Set default work depth: fast | standard | deep (default: standard)
+      --dry-run      (upgrade only) Show what would change without writing files
   -h, --help         Show this help
   -v, --version      Print version
 
 ${pc.bold('Examples:')}
   npx create-vasvibe my-app
-  npx create-vasvibe my-app --yes
   npx create-vasvibe my-app --yes --no-claude --no-github
+  npx create-vasvibe my-app --depth=fast  Scaffold with fast work depth (prototype mode)
+  npx create-vasvibe upgrade              Upgrade current directory
+  npx create-vasvibe upgrade ./my-app     Upgrade specific project
+  npx create-vasvibe upgrade --dry-run    Preview upgrade without writing
 `;
 
 function parseArgs(argv) {
   const args = argv.slice(2);
   const flags = {
     yes: false,
-    update: false,
     git: true,
     opencode: true,
     claude: true,
@@ -44,6 +49,8 @@ function parseArgs(argv) {
     workflows: true,
     help: false,
     version: false,
+    dryRun: false,
+    depth: null,
   };
   const positional = [];
 
@@ -53,9 +60,8 @@ function parseArgs(argv) {
       case '--yes':
         flags.yes = true;
         break;
-      case '-u':
-      case '--update':
-        flags.update = true;
+      case '--dry-run':
+        flags.dryRun = true;
         break;
       case '--no-git':
         flags.git = false;
@@ -81,6 +87,15 @@ function parseArgs(argv) {
         flags.version = true;
         break;
       default:
+        if (a.startsWith('--depth=')) {
+          const val = a.slice('--depth='.length);
+          if (!['fast', 'standard', 'deep'].includes(val)) {
+            log.error(`Invalid depth value "${val}". Use: fast | standard | deep`);
+            process.exit(1);
+          }
+          flags.depth = val;
+          break;
+        }
         if (a.startsWith('-')) {
           log.error(`Unknown flag: ${a}`);
           console.log(HELP);
@@ -112,6 +127,30 @@ export async function main(argv) {
     return;
   }
 
+  // --- Upgrade subcommand ---
+  if (positional[0] === 'upgrade') {
+    const pkg = await readPkg();
+    const targetDir = positional[1]
+      ? path.resolve(process.cwd(), positional[1])
+      : process.cwd();
+
+    if (!(await isVasvibeProject(targetDir))) {
+      log.error(`No vasvibe project found at ${targetDir}`);
+      log.step('Run this command from inside a vasvibe project directory.');
+      process.exit(1);
+    }
+
+    log.title('\n  create-vasvibe upgrade\n');
+    try {
+      await runUpgrade({ targetDir, newVersion: pkg.version, dryRun: flags.dryRun });
+    } catch (err) {
+      log.error(`Upgrade failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // --- Scaffold subcommand (default) ---
   const argInput = positional[0];
   // The arg may be a path (e.g. /tmp/foo or ./foo); use its basename as the
   // logical project name, and resolve the full path as the target directory.
@@ -131,14 +170,17 @@ export async function main(argv) {
     ? path.resolve(process.cwd(), argInput)
     : path.resolve(process.cwd(), projectName);
 
-  // Safety: target must not exist or must be empty, unless --update is passed.
-  if (!flags.update && await pathExists(targetDir)) {
+  // Safety: target must not exist or must be empty.
+  if (await pathExists(targetDir)) {
     if (!(await isDirEmpty(targetDir))) {
-      log.error(`Target directory "${projectName}" already exists and is not empty. Use --update to overwrite agent files.`);
+      log.error(`Target directory "${projectName}" already exists and is not empty.`);
+      log.step(`To update agent files in an existing project, use: ${pc.cyan('npx create-vasvibe upgrade')}`);
       process.exit(1);
     }
   }
 
+  const pkg = await readPkg();
+
   log.blank();
   log.step(`Scaffolding into ${pc.cyan(targetDir)}`);
 
@@ -146,6 +188,8 @@ export async function main(argv) {
     await scaffold({
       targetDir,
       projectName,
+      version: pkg.version,
+      workDepth: answers.workDepth,
       includeOpencode: answers.includeOpencode,
       includeClaude: answers.includeClaude,
       includeGithub: answers.includeGithub,

package/src/prompts.mjs

@@ -13,6 +13,7 @@ export async function runPrompts({ argName, flags }) {
       includeGithub: flags.github !== false,
       includeWorkflows: flags.workflows !== false,
       initGit: flags.git !== false,
+      workDepth: flags.depth || 'standard',
     };
   }
 
@@ -72,6 +73,30 @@ export async function runPrompts({ argName, flags }) {
         active: 'yes',
         inactive: 'no',
       },
+      {
+        type: flags.depth ? null : 'select',
+        name: 'workDepth',
+        message: 'Default work depth for all agents?',
+        hint: 'Can be changed anytime in project_overview.md → ## 7. Project Settings',
+        choices: [
+          {
+            title: 'standard (recommended)',
+            description: 'Full spec, unit tests, code review — the default for everyday production development.',
+            value: 'standard',
+          },
+          {
+            title: 'fast',
+            description: 'Core feature only, skip optional steps (unit tests, full docs, edge cases) — good for prototypes and MVPs.',
+            value: 'fast',
+          },
+          {
+            title: 'deep',
+            description: 'Maximum thoroughness — full security review, all edge cases, strict validation — for critical systems.',
+            value: 'deep',
+          },
+        ],
+        initial: 0,
+      },
     ],
     { onCancel },
   );
@@ -83,5 +108,6 @@ export async function runPrompts({ argName, flags }) {
     includeGithub: flags.github === false ? false : answers.includeGithub ?? true,
     includeWorkflows: flags.workflows === false ? false : answers.includeWorkflows ?? true,
     initGit: flags.git === false ? false : answers.initGit ?? true,
+    workDepth: flags.depth || answers.workDepth || 'standard',
   };
 }

package/src/scaffold.mjs

@@ -6,6 +6,7 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { copyDir, removePath, replaceInFile, pathExists } from './utils.mjs';
+import { writeVersionFile } from './upgrade.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // packages/create-vasvibe/src → packages/create-vasvibe/template
@@ -21,6 +22,8 @@ const TOOLCHAIN_PATHS = {
 export async function scaffold({
   targetDir,
   projectName,
+  version,
+  workDepth = 'standard',
   includeOpencode,
   includeClaude,
   includeGithub,
@@ -52,11 +55,16 @@ export async function scaffold({
 
   // 4. Replace placeholders in well-known files.
   const year = String(new Date().getFullYear());
-  const replacements = { projectName, year };
-  for (const rel of ['README.md', 'PROJECT_README.example.md', '.gitignore', 'AGENT_PERSONAS.md', 'GIT_STRUCTURE_GUIDE.md']) {
+  const replacements = { projectName, year, workDepth };
+  for (const rel of ['README.md', 'PROJECT_README.example.md', '.gitignore', 'AGENT_PERSONAS.md', 'GIT_STRUCTURE_GUIDE.md', 'project_overview_example.md']) {
     const f = path.join(targetDir, rel);
     if (await pathExists(f)) await replaceInFile(f, replacements);
   }
+
+  // 5. Write version tracking file.
+  if (version) {
+    await writeVersionFile(targetDir, version);
+  }
 }
 
 async function removeAll(targetDir, relPaths) {

package/src/upgrade.mjs

@@ -0,0 +1,121 @@
+// src/upgrade.mjs
+// Upgrade an existing vasvibe project: re-copy framework files (agents, schemas,
+// workflows) without touching user-generated content (codes/, specifications/,
+// task/, state/, project_overview.md, etc.).
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { copyDir, pathExists, log } from './utils.mjs';
+import pc from 'picocolors';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = path.resolve(__dirname, '..', 'template');
+const VERSION_FILE = '.vasvibe-version';
+
+// Only these paths are safe to overwrite on upgrade.
+// User content (codes/, specifications/, task/, state/, project_overview.md) is never touched.
+const FRAMEWORK_PATHS = [
+  { src: '.opencode', dest: '.opencode' },
+  { src: '.claude', dest: '.claude' },
+  { src: '.agents', dest: '.agents' },
+  { src: '.github/prompts', dest: '.github/prompts' },
+  { src: 'agent', dest: 'agent' },
+  { src: 'schemas', dest: 'schemas' },
+];
+
+export async function readVersionFile(projectDir) {
+  const versionPath = path.join(projectDir, VERSION_FILE);
+  try {
+    const content = await fs.readFile(versionPath, 'utf8');
+    return content.trim();
+  } catch {
+    return null;
+  }
+}
+
+export async function writeVersionFile(projectDir, version) {
+  await fs.writeFile(path.join(projectDir, VERSION_FILE), version + '\n', 'utf8');
+}
+
+export async function isVasvibeProject(projectDir) {
+  // A vasvibe project has either .vasvibe-version or at least one agent directory.
+  if (await pathExists(path.join(projectDir, VERSION_FILE))) return true;
+  if (await pathExists(path.join(projectDir, 'agent/workflows'))) return true;
+  if (await pathExists(path.join(projectDir, '.opencode/agents'))) return true;
+  return false;
+}
+
+export async function upgrade({ targetDir, currentVersion, newVersion, dryRun = false }) {
+  if (!(await pathExists(TEMPLATE_DIR))) {
+    throw new Error(`Template directory not found at ${TEMPLATE_DIR}.`);
+  }
+
+  const updated = [];
+  const skipped = [];
+
+  for (const { src, dest } of FRAMEWORK_PATHS) {
+    const srcPath = path.join(TEMPLATE_DIR, src);
+    const destPath = path.join(targetDir, dest);
+
+    if (!(await pathExists(srcPath))) {
+      skipped.push(src);
+      continue;
+    }
+    // Only update if the destination already exists in the project
+    // (respect the user's original toolchain choices).
+    if (!(await pathExists(destPath))) {
+      skipped.push(dest + ' (not in project)');
+      continue;
+    }
+
+    if (!dryRun) {
+      await copyDir(srcPath, destPath);
+    }
+    updated.push(dest);
+  }
+
+  if (!dryRun) {
+    await writeVersionFile(targetDir, newVersion);
+  }
+
+  return { updated, skipped };
+}
+
+export async function runUpgrade({ targetDir, newVersion, dryRun }) {
+  const currentVersion = await readVersionFile(targetDir);
+
+  log.blank();
+  if (currentVersion) {
+    log.info(`Current version: ${pc.yellow(currentVersion)}`);
+  } else {
+    log.warn('No .vasvibe-version file found — project may have been created before version tracking was added.');
+  }
+  log.info(`Upgrading to:    ${pc.green(newVersion)}`);
+  log.blank();
+
+  if (dryRun) {
+    log.step('Dry run — no files will be changed.');
+    log.blank();
+  }
+
+  const { updated, skipped } = await upgrade({ targetDir, currentVersion, newVersion, dryRun });
+
+  for (const p of updated) {
+    log.success(`Updated: ${pc.cyan(p)}`);
+  }
+  for (const p of skipped) {
+    log.step(`Skipped: ${pc.dim(p)}`);
+  }
+
+  log.blank();
+  if (dryRun) {
+    log.info('Run without --dry-run to apply the upgrade.');
+  } else {
+    log.success(`Upgraded to ${pc.green(newVersion)}`);
+    log.blank();
+    log.step('Review the changes with ' + pc.cyan('git diff') + ' before committing.');
+    log.step('Your codes/, specifications/, task/, and state/ directories were not touched.');
+  }
+  log.blank();
+}

package/template/.agents/agents/backend/agent.json

@@ -0,0 +1,44 @@
+{
+  "name": "backend",
+  "description": "Senior Backend Engineer \u2014 implements API, business logic & DB access per the API Contract (depth=standard|deep).",
+  "hidden": true,
+  "config": {
+    "customAgent": {
+      "systemPromptSections": [
+        {
+          "title": "Agent System Instructions",
+          "content": "You are the backend Agent. Read and follow ALL instructions in agent/workflows/backend.md as your complete system prompt. That file is your source of truth."
+        }
+      ],
+      "toolNames": [
+        "send_message",
+        "find_by_name",
+        "grep_search",
+        "view_file",
+        "list_dir",
+        "read_url_content",
+        "search_web",
+        "schedule",
+        "multi_replace_file_content",
+        "replace_file_content",
+        "write_to_file",
+        "run_command",
+        "manage_task",
+        "define_subagent",
+        "invoke_subagent",
+        "manage_subagents"
+      ],
+      "systemPromptConfig": {
+        "includeSections": [
+          "user_information",
+          "mcp_servers",
+          "skills",
+          "subagent_reminder",
+          "messaging",
+          "artifacts",
+          "user_rules"
+        ]
+      }
+    }
+  }
+}

package/template/.agents/agents/data-architect/agent.json

@@ -0,0 +1,43 @@
+{
+  "name": "data-architect",
+  "description": "Data Architect \u2014 designs data model, ERD, schema, indexing & data governance during planning.",
+  "hidden": true,
+  "config": {
+    "customAgent": {
+      "systemPromptSections": [
+        {
+          "title": "Agent System Instructions",
+          "content": "You are the data-architect Agent. Read and follow ALL instructions in agent/workflows/data-architect.md as your complete system prompt. That file is your source of truth."
+        }
+      ],
+      "toolNames": [
+        "send_message",
+        "find_by_name",
+        "grep_search",
+        "view_file",
+        "list_dir",
+        "read_url_content",
+        "search_web",
+        "schedule",
+        "multi_replace_file_content",
+        "replace_file_content",
+        "write_to_file",
+        "manage_task",
+        "define_subagent",
+        "invoke_subagent",
+        "manage_subagents"
+      ],
+      "systemPromptConfig": {
+        "includeSections": [
+          "user_information",
+          "mcp_servers",
+          "skills",
+          "subagent_reminder",
+          "messaging",
+          "artifacts",
+          "user_rules"
+        ]
+      }
+    }
+  }
+}

package/template/.agents/agents/discovery/agent.json

@@ -0,0 +1,43 @@
+{
+  "name": "discovery",
+  "description": "Product Discovery Lead & Business Analyst \u2014 gathers requirements interactively from the human before any document is created.",
+  "hidden": false,
+  "config": {
+    "customAgent": {
+      "systemPromptSections": [
+        {
+          "title": "Agent System Instructions",
+          "content": "You are the discovery Agent. Read and follow ALL instructions in agent/workflows/discovery.md as your complete system prompt. That file is your source of truth."
+        }
+      ],
+      "toolNames": [
+        "send_message",
+        "find_by_name",
+        "grep_search",
+        "view_file",
+        "list_dir",
+        "read_url_content",
+        "search_web",
+        "schedule",
+        "multi_replace_file_content",
+        "replace_file_content",
+        "write_to_file",
+        "manage_task",
+        "define_subagent",
+        "invoke_subagent",
+        "manage_subagents"
+      ],
+      "systemPromptConfig": {
+        "includeSections": [
+          "user_information",
+          "mcp_servers",
+          "skills",
+          "subagent_reminder",
+          "messaging",
+          "artifacts",
+          "user_rules"
+        ]
+      }
+    }
+  }
+}

package/template/.agents/agents/frontend/agent.json

@@ -0,0 +1,44 @@
+{
+  "name": "frontend",
+  "description": "Senior Frontend Engineer & UI Specialist \u2014 implements UI & API integration per the design system (depth=standard|deep).",
+  "hidden": true,
+  "config": {
+    "customAgent": {
+      "systemPromptSections": [
+        {
+          "title": "Agent System Instructions",
+          "content": "You are the frontend Agent. Read and follow ALL instructions in agent/workflows/frontend.md as your complete system prompt. That file is your source of truth."
+        }
+      ],
+      "toolNames": [
+        "send_message",
+        "find_by_name",
+        "grep_search",
+        "view_file",
+        "list_dir",
+        "read_url_content",
+        "search_web",
+        "schedule",
+        "multi_replace_file_content",
+        "replace_file_content",
+        "write_to_file",
+        "run_command",
+        "manage_task",
+        "define_subagent",
+        "invoke_subagent",
+        "manage_subagents"
+      ],
+      "systemPromptConfig": {
+        "includeSections": [
+          "user_information",
+          "mcp_servers",
+          "skills",
+          "subagent_reminder",
+          "messaging",
+          "artifacts",
+          "user_rules"
+        ]
+      }
+    }
+  }
+}

package/template/.agents/agents/reliability/agent.json

@@ -0,0 +1,44 @@
+{
+  "name": "reliability",
+  "description": "Reliability & Performance Engineer \u2014 performance, resilience & load testing during per-release hardening.",
+  "hidden": true,
+  "config": {
+    "customAgent": {
+      "systemPromptSections": [
+        {
+          "title": "Agent System Instructions",
+          "content": "You are the reliability Agent. Read and follow ALL instructions in agent/workflows/reliability.md as your complete system prompt. That file is your source of truth."
+        }
+      ],
+      "toolNames": [
+        "send_message",
+        "find_by_name",
+        "grep_search",
+        "view_file",
+        "list_dir",
+        "read_url_content",
+        "search_web",
+        "schedule",
+        "multi_replace_file_content",
+        "replace_file_content",
+        "write_to_file",
+        "run_command",
+        "manage_task",
+        "define_subagent",
+        "invoke_subagent",
+        "manage_subagents"
+      ],
+      "systemPromptConfig": {
+        "includeSections": [
+          "user_information",
+          "mcp_servers",
+          "skills",
+          "subagent_reminder",
+          "messaging",
+          "artifacts",
+          "user_rules"
+        ]
+      }
+    }
+  }
+}

package/template/.agents/agents/security/agent.json

@@ -0,0 +1,44 @@
+{
+  "name": "security",
+  "description": "Application Security Expert \u2014 security standards (planning) + threat modeling, OWASP audit & fixes (hardening).",
+  "hidden": false,
+  "config": {
+    "customAgent": {
+      "systemPromptSections": [
+        {
+          "title": "Agent System Instructions",
+          "content": "You are the security Agent. Read and follow ALL instructions in agent/workflows/security.md as your complete system prompt. That file is your source of truth."
+        }
+      ],
+      "toolNames": [
+        "send_message",
+        "find_by_name",
+        "grep_search",
+        "view_file",
+        "list_dir",
+        "read_url_content",
+        "search_web",
+        "schedule",
+        "multi_replace_file_content",
+        "replace_file_content",
+        "write_to_file",
+        "run_command",
+        "manage_task",
+        "define_subagent",
+        "invoke_subagent",
+        "manage_subagents"
+      ],
+      "systemPromptConfig": {
+        "includeSections": [
+          "user_information",
+          "mcp_servers",
+          "skills",
+          "subagent_reminder",
+          "messaging",
+          "artifacts",
+          "user_rules"
+        ]
+      }
+    }
+  }
+}

package/template/.agents/agents/ux-designer/agent.json

@@ -0,0 +1,43 @@
+{
+  "name": "ux-designer",
+  "description": "UX/UI Designer \u2014 designs the design system (colors, typography, components, motion, a11y) during planning.",
+  "hidden": true,
+  "config": {
+    "customAgent": {
+      "systemPromptSections": [
+        {
+          "title": "Agent System Instructions",
+          "content": "You are the ux-designer Agent. Read and follow ALL instructions in agent/workflows/ux-designer.md as your complete system prompt. That file is your source of truth."
+        }
+      ],
+      "toolNames": [
+        "send_message",
+        "find_by_name",
+        "grep_search",
+        "view_file",
+        "list_dir",
+        "read_url_content",
+        "search_web",
+        "schedule",
+        "multi_replace_file_content",
+        "replace_file_content",
+        "write_to_file",
+        "manage_task",
+        "define_subagent",
+        "invoke_subagent",
+        "manage_subagents"
+      ],
+      "systemPromptConfig": {
+        "includeSections": [
+          "user_information",
+          "mcp_servers",
+          "skills",
+          "subagent_reminder",
+          "messaging",
+          "artifacts",
+          "user_rules"
+        ]
+      }
+    }
+  }
+}

package/template/.agents/workflows/build-feature.md

@@ -0,0 +1,21 @@
+---
+description: Jalankan Fase 2 (Pengerjaan) — implementasi satu fitur dari spec yang sudah ada.
+---
+
+Jalankan **Fase 2 — Pengerjaan** untuk fitur: **$ARGUMENTS**
+
+Langkah:
+1. **PM** → buat task & detail file dari spec
+2. **Analyst (spec-lock)** → matangkan AC detail untuk fitur ini
+3. **Implementasi sesuai depth:**
+   - `depth=fast` → **Developer** (fullstack tunggal)
+   - `depth=standard|deep` → **Backend Engineer** ∥ **Frontend Engineer** (paralel, honor API Contract)
+4. **QA** → static review + unit test
+5. **GATE — Code review lulus:** Human review pakai QA report.
+
+**Aturan orkestrasi (WAJIB):**
+- Kamu adalah **Orchestrator** di thread utama. Delegasikan tiap langkah ke subagent yang disebut menggunakan Task tool (Claude Code) / agent invocation (OpenCode).
+- **BERHENTI di setiap GATE / CHECKPOINT** dan minta persetujuan human secara eksplisit sebelum lanjut.
+- Definisi kanonik pipeline: baca `agent/workflows/orchestrator.md`. Model fase & kepemilikan dokumen: `agent/workflows/_shared/phases.md`.
+- Hormati `WORK_DEPTH` dari `project_overview.md` (override dengan `depth=` di argumen jika ada).
+- Jika muncul perubahan di tengah pipeline, ikuti `agent/workflows/_shared/change-management.md` (No Silent Changes).