pan-stack-cli 0.1.2 → 0.1.4

package/README.md

@@ -1,152 +1,216 @@
 # pan-stack-cli
 
-CLI toàn cục cho PAN Stack workspace — thay script `./pan` ở root dự án.
-
-Cài một lần, dùng ở mọi dự án có `.project.yaml`:
+Global CLI for PAN Stack workspaces. Install once, use in any project that has
+`.project.yaml`.
 
 ```bash
 npm i -g pan-stack-cli
-# hoặc từ source (trước khi publish npm):
-npm i -g /path/to/.pan/pan-stack-cli
+# or from source before npm publish:
+npm i -g /path/to/pan-stack-cli
 ```
 
-Sau đó gõ `pan` thay cho `./pan`.
+## What is PAN Stack?
+
+PAN Stack is a **workspace shell** for coding with AI agents — not a monorepo that
+contains every product repository. The stack repo holds:
+
+- Agent skills and prompts (`.claude`, `.cursor`, `.codex`)
+- Workspace manifests (`.project.yaml`, `.pan.yaml`)
+- Team docs and coordination files
 
-## Yêu cầu
+Product source code lives in separate repositories listed in `.project.yaml`. The
+`pan` CLI ties them together: clone all repos, run git ops across the workspace,
+and execute project commands defined in `.pan.yaml`.
+
+```text
+bookshop-stack/                 # PAN Stack workspace (shell)
+  .project.yaml                 # Which repos belong to this workspace
+  .pan.yaml                     # Workspace-level pan commands
+  .claude/skills/               # Claude Code skills
+  .cursor/skills/               # Cursor agent skills
+  .codex/skills/                # Codex agent skills
+  apps/
+    web/                        # bookshop-web (cloned product repo)
+    api/                        # bookshop-api (cloned product repo)
+```
+
+Run `pan create` to scaffold this layout with the shared `writing-guidelines`
+skill pre-installed for all three agent folders.
+
+## Requirements
 
 - Node.js 18+
-- Git (cho `pan clone`, `pull`, `fetch`, `push`, `grv`, `gst`)
-- Công cụ riêng từng lệnh dự án (pnpm, docker, curl, …)
+- Git (for `pan clone`, `pull`, `fetch`, `push`, `grv`, `gst`)
 
-## Lệnh git (built-in)
+## Windows support
 
-Đọc `repositories` từ `.project.yaml` gần nhất (walk-up từ thư mục hiện tại):
+Built-in commands (`create`, `clone`, `pull`, `push`, `fetch`, `grv`, `gst`) run on
+Windows, macOS, and Linux. Notes for Windows:
 
-| Lệnh | Việc |
-|------|------|
-| `pan clone` | Clone tất cả repo trong manifest |
-| `pan pull` | Pull tất cả repo đã clone |
-| `pan fetch` | Fetch all remotes |
-| `pan push` | Push và set upstream (`-u origin HEAD`) |
-| `pan grv` | `git remote -v` — URL đầy đủ cho workspace + từng repo con |
-| `pan gst` | `git status` cho workspace + từng repo con (vd `pan gst -sb`) |
+- `shell:` blocks in `.pan.yaml` run through **bash** on all platforms (Git Bash on
+  Windows, system bash on macOS/Linux). Use `exec:` for simple one-liners (`npm test`)
+  when possible; those work without Bash.
+- Install **Git for Windows** if bash is not already on `PATH`.
+- Set `PAN_PROJECT_ROOTS` with **semicolon** separators (`C:\work\a;C:\work\b`).
+  Do not use `:` — it conflicts with drive letters.
+- Optional: set `PAN_GIT_BASH` to the full path of `bash.exe` if Git is installed in
+  a non-standard location.
 
-Tuỳ chọn git (forward xuống script):
+## Bootstrap a new workspace
 
-- `--base-dir DIR` — thư mục gốc cho path repo con (mặc định: thư mục chứa `.project.yaml`; tự walk-up từ cwd nếu không có ngay tại đó)
-- `--dry-run` — chỉ in lệnh
-- `[manifest]` — đường dẫn manifest (mặc định: `.project.yaml`)
+```bash
+mkdir ~/work && cd ~/work
+pan create                    # prompts for folder name
+# or
+pan create bookshop-stack     # non-interactive
 
-## Lệnh dự án (từ `.pan.yaml`)
+cd bookshop-stack
+# Edit .project.yaml — replace repo_url_to_be_filled with real URLs
+pan clone
+pan install
+```
 
-Hai lớp cấu hình:
+`pan create` fails if the target folder already exists.
 
-| File | Vai trò |
-|------|---------|
-| `.project.yaml` | Workspace: danh sách repo (`repositories`) — **không** chứa `commands` |
-| `.pan.yaml` | Lệnh `pan` — đặt ở workspace root và/hoặc từng repo con |
+## Configuration files
 
-CLI load **tất cả** `.pan.yaml` trong workspace (root + mỗi `repositories[].path`). Lệnh trùng tên → hỏi chọn repo (`--project`) hoặc tự chọn nếu arg khớp `targets` (vd `pan test fe`).
+Two files drive the CLI. Keep responsibilities separate:
 
-### Schema `.pan.yaml` (repo con)
+| File | Role |
+|------|------|
+| `.project.yaml` | Workspace manifest — lists `repositories` (name, url, path). **No commands.** |
+| `.pan.yaml` | `pan` commands — at workspace root and/or inside each child repo |
 
-`cwd` / `exec` tương đối **root repo** (thư mục chứa file `.pan.yaml`):
+### `.project.yaml` example
 
 ```yaml
-commands:
-  be:
-    description: Deploy backend local
-    exec: scripts/deploy.sh
+project: bookshop-stack
+managed_by: your-team
+
+stack:
+  repo: https://github.com/example/bookshop-stack.git
+
+repositories:
+  - name: bookshop-web
+    description: Customer-facing web application
+    url: https://github.com/example/bookshop-web.git
+    path: apps/web
+  - name: bookshop-api
+    description: REST API service
+    url: https://github.com/example/bookshop-api.git
+    path: apps/api
+```
+
+### `.pan.yaml` — workspace root
+
+Orchestration commands. Paths are relative to the workspace root. Use
+`PAN_WORKSPACE_ROOT` in shell blocks:
 
+```yaml
+commands:
   install:
     alias: i
-    description: Cài dependencies (pan i hoặc pan install)
+    description: Install dependencies across cloned repositories
     shell: |
       set -euo pipefail
-      pnpm install
+      root="${PAN_WORKSPACE_ROOT}"
+      for dir in apps/web apps/api; do
+        [[ -d "$root/$dir" ]] || { echo "Missing: $root/$dir" >&2; exit 1; }
+        (cd "$root/$dir" && npm install)
+      done
 
-  lint:
-    shell: |
-      set -euo pipefail
-      pnpm lint
+  test:
+    default: web
+    description: Run tests (web | api)
+    targets:
+      web:
+        cwd: apps/web
+        exec: npm test
+      api:
+        cwd: apps/api
+        exec: npm test
 ```
 
-Alias: `alias: i` hoặc `aliases: i, ins` (cách nhau bằng dấu phẩy).
+### `.pan.yaml` — child repo
 
-### Schema `.pan.yaml` (workspace root)
-
-Lệnh orchestration — `cwd` tương đối workspace root; dùng `PAN_WORKSPACE_ROOT` trong shell:
+Place a `.pan.yaml` inside a cloned repo. `cwd` / `exec` are relative to that
+repo's root:
 
 ```yaml
 commands:
-  install:
-    shell: |
-      cd "${PAN_WORKSPACE_ROOT}/apps/frontend" && pnpm install
+  dev:
+    description: Start local dev server
+    exec: npm run dev
 
-  test:
-    default: fe
-    targets:
-      be:
-        cwd: apps/backend
-        exec: ./gradlew test
-      fe:
-        cwd: apps/frontend
-        exec: pnpm test
+  lint:
+    shell: |
+      set -euo pipefail
+      npm run lint
 ```
 
-### Biến môi trường
+Aliases: `alias: i` or `aliases: i, ins` (comma-separated).
 
-| Biến | Ý nghĩa |
-|------|---------|
-| `PAN_WORKSPACE_ROOT` | Thư mục chứa `.project.yaml` |
-| `PAN_REPO_ROOT` | Thư mục chứa `.pan.yaml` đang chạy |
-| `PAN_PROJECT_ROOT` | Alias của `PAN_WORKSPACE_ROOT` |
-| `PAN_ARG_1`, … | Args sau tên lệnh |
+## Built-in git commands
 
-### Nhiều repo trùng tên lệnh
+Read `repositories` from the nearest `.project.yaml` (walk-up from cwd):
 
-CLI quét workspace gần nhất (walk-up `.project.yaml`) rồi load mọi `.pan.yaml` con.
+| Command | Action |
+|---------|--------|
+| `pan clone` | Clone all repositories in the manifest |
+| `pan pull` | Pull all cloned repositories |
+| `pan fetch` | Fetch all remotes |
+| `pan push` | Push all repos (`-u origin HEAD` by default) |
+| `pan grv` | `git remote -v` for workspace + each child repo |
+| `pan gst` | `git status` for workspace + each child repo |
 
-## Ví dụ (CSDL-CC)
+Git options:
 
-Trong repo `btp-csdl-cc` (đã có `.project.yaml`):
+- `--base-dir DIR` — base for relative repo paths (default: directory containing `.project.yaml`)
+- `--dry-run` — print commands only
+- `[manifest]` — manifest path (default: `.project.yaml`)
 
-```bash
-cd ~/work/btp/btp-csdl-cc
+Works from child repo directories — the CLI walks up to find `.project.yaml`.
 
-pan clone
-pan install
-pan be                    # deploy backend :8080
-pan fe                    # Vite :5173
-pan faker                 # pan-faker :8090
-pan test fe               # vitest
-pan demo uc2              # use case demo qua faker
-pan status
-pan down                  # docker compose down (giữ volume)
-pan reset -y              # xoá volume + deploy lại
-```
+## Project commands
+
+The CLI loads **all** `.pan.yaml` files in the workspace (root + each
+`repositories[].path`). When the same command name appears in multiple repos,
+use `--project <name>` or pick interactively.
+
+### Environment variables
 
-## `./pan` ở root repo
+| Variable | Meaning |
+|----------|---------|
+| `PAN_WORKSPACE_ROOT` | Directory containing `.project.yaml` |
+| `PAN_REPO_ROOT` | Directory containing the active `.pan.yaml` |
+| `PAN_PROJECT_ROOT` | Alias of `PAN_WORKSPACE_ROOT` |
+| `PAN_ARG_1`, … | Arguments after the command name |
 
-Script `./pan` là shim mỏng:
+### Registry (optional)
 
-1. Dùng `pan` global nếu đã cài
-2. Fallback `node .pan/pan-stack-cli/bin/pan.js`
+- `PAN_PROJECT_ROOTS` — extra workspace roots (`;` on Windows, `:` or `;` on Unix)
+- `~/.pan/projects` — one workspace root per line
 
-## Cấu trúc package
+## Package layout
 
 ```text
-.pan/pan-stack-cli/
-  bin/pan.js           # entry CLI
-  lib/                 # manifest, discover, run-command, git/
-  lib/git/             # git-clone, pull, fetch, push, grv, gst (+ helpers)
-  references/          # hướng dẫn publish npm
+pan-stack-cli/
+  bin/pan.js              # CLI entry
+  lib/
+    create.js             # pan create scaffold
+    discover.js             # workspace discovery
+    platform.js             # Windows/cross-platform helpers
+    manifest.js             # YAML parsing
+    run-command.js        # command execution
+    git/                  # clone, pull, push, fetch, grv, gst
+  templates/workspace/    # pan create template
+  references/             # npm publish docs
 ```
 
-## Phát triển local
+## Local development
 
-Cài global từ source (khuyên dùng trước publish): [references/npm-development.md](references/npm-development.md).
+Install globally from source: [references/npm-development.md](references/npm-development.md).
 
-## Publish npm
+## Publish to npm
 
-Xem [references/npm-release.md](references/npm-release.md).
+See [references/npm-release.md](references/npm-release.md).

package/bin/pan.js

@@ -6,9 +6,11 @@ const {
   findSourcesWithCommand,
   formatProjectList,
   isBuiltinGitCommand,
+  isBuiltinWorkspaceCommand,
 } = require("../lib/discover");
 const { listCommands } = require("../lib/manifest");
 const { runWithProjectResolution, runGitScript, sourceLabel } = require("../lib/run-command");
+const { runCreate } = require("../lib/create");
 
 const GIT_SCRIPT_MAP = {
   clone: "git-clone.js",
@@ -48,43 +50,45 @@ function parseGlobalArgs(argv) {
 function printUsage() {
   console.log(`usage: pan <command> [options] [-- args...]
 
-repo commands (built-in):
+workspace commands (built-in):
+  create  Scaffold a new PAN Stack workspace (prompts for folder name)
   clone   Clone all repositories from .project.yaml
   pull    Pull latest changes for all repositories
   fetch   Fetch all remotes for all repositories
   push    Push all repositories and set upstream
-  grv     List git remotes -v (URL đầy đủ) cho workspace + repo con
-  gst     Git status cho workspace + repo con (forward args: pan gst -sb)
+  grv     List git remotes -v for workspace + child repos
+  gst     Git status for workspace + child repos (e.g. pan gst -sb)
 
 project commands:
-  Gom từ .pan.yaml (workspace root + từng repo con trong .project.yaml)
+  Loaded from .pan.yaml (workspace root + each repo in .project.yaml)
 
 options:
-  --project NAME   Chọn repo khi nhiều .pan.yaml có cùng lệnh
-  --base-dir DIR   (git commands) thư mục gốc repo con
-  --dry-run        (git commands) chỉ in lệnh
-  -h, --help       Hiện trợ giúp
+  --project NAME   Pick a repo when multiple .pan.yaml files define the same command
+  --base-dir DIR   (git commands) base directory for child repo paths
+  --dry-run        (git commands) print commands only
+  -h, --help       Show help
 
 env:
-  PAN_PROJECT_ROOTS   Danh sách root workspace (phân cách bằng , hoặc ;)
-  ~/.pan/projects     Mỗi dòng một workspace root
+  PAN_PROJECT_ROOTS   Semicolon-separated workspace roots (; on Windows, : or ; on Unix)
+  ~/.pan/projects     One workspace root per line
 
 examples:
+  pan create
+  pan create bookshop-stack
   pan clone
   pan grv
-  pan be
   pan test fe
-  pan test --project csdl-cc-b-frontend-e2e
+  pan test --project bookshop-web
 `);
 }
 
 function printAllCommands(sources) {
   if (sources.length === 0) {
-    console.log("Chưa tìm thấy .pan.yaml (workspace hoặc repo con).");
+    console.log("No .pan.yaml found (workspace or child repos).");
     return;
   }
 
-  console.log("Lệnh đã load:");
+  console.log("Loaded commands:");
   for (const source of sources) {
     const commands = listCommands(source);
     if (commands.length === 0) {
@@ -119,6 +123,11 @@ async function main() {
 
   const { command, args, project } = parsed;
 
+  if (command === "create") {
+    await runCreate(args);
+    return;
+  }
+
   if (isBuiltinGitCommand(command)) {
     const gitArgs = [...args];
     if (command === "push" && !gitArgs.includes("--set-upstream")) {
@@ -128,6 +137,10 @@ async function main() {
     return;
   }
 
+  if (isBuiltinWorkspaceCommand(command)) {
+    throw new Error(`Unknown built-in command: ${command}`);
+  }
+
   const allSources = loadAllCommandSources();
   const matches = findSourcesWithCommand(command);
   if (matches.length > 1 && !project && process.stdin.isTTY) {

package/lib/create.js

@@ -0,0 +1,87 @@
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+const { validateFolderName } = require("./platform");
+
+const TEMPLATE_ROOT = path.join(__dirname, "..", "templates", "workspace");
+
+function promptFolderName() {
+  return new Promise((resolve, reject) => {
+    if (!process.stdin.isTTY) {
+      reject(new Error("Folder name required: pan create <folder-name>"));
+      return;
+    }
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question("Workspace folder name: ", (answer) => {
+      rl.close();
+      const name = answer.trim();
+      if (!name) {
+        reject(new Error("Folder name cannot be empty."));
+        return;
+      }
+      resolve(name);
+    });
+  });
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function applyPlaceholders(targetDir, folderName) {
+  const files = [".project.yaml", "README.md"];
+  for (const relativePath of files) {
+    const filePath = path.join(targetDir, relativePath);
+    if (!fs.existsSync(filePath)) {
+      continue;
+    }
+    const content = fs.readFileSync(filePath, "utf8");
+    fs.writeFileSync(filePath, content.replaceAll("__PROJECT_NAME__", folderName));
+  }
+}
+
+async function runCreate(args = []) {
+  let folderName = args[0]?.trim();
+  if (!folderName) {
+    folderName = await promptFolderName();
+  }
+
+  validateFolderName(folderName);
+
+  const targetDir = path.resolve(process.cwd(), folderName);
+  if (fs.existsSync(targetDir)) {
+    throw new Error(`Folder already exists: ${targetDir}`);
+  }
+
+  if (!fs.existsSync(TEMPLATE_ROOT)) {
+    throw new Error(`Template not found: ${TEMPLATE_ROOT}`);
+  }
+
+  copyDir(TEMPLATE_ROOT, targetDir);
+  applyPlaceholders(targetDir, folderName);
+
+  console.log(`Created PAN Stack workspace: ${targetDir}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${folderName}`);
+  console.log("  # Edit .project.yaml with your repository URLs");
+  console.log("  pan clone");
+}
+
+module.exports = {
+  runCreate,
+};

package/lib/discover.js

@@ -1,6 +1,7 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const { splitEnvList } = require("./platform");
 const {
   PAN_CONFIG_FILE,
   loadManifest,
@@ -12,15 +13,13 @@ const {
 } = require("./manifest");
 
 const BUILTIN_GIT_COMMANDS = new Set(["clone", "pull", "fetch", "push", "grv", "gst"]);
+const BUILTIN_WORKSPACE_COMMANDS = new Set(["create", ...BUILTIN_GIT_COMMANDS]);
 
 function readProjectRoots() {
   const roots = [];
   const fromEnv = process.env.PAN_PROJECT_ROOTS || "";
-  for (const part of fromEnv.split(/[:;,]/)) {
-    const trimmed = part.trim();
-    if (trimmed) {
-      roots.push(path.resolve(trimmed));
-    }
+  for (const part of splitEnvList(fromEnv)) {
+    roots.push(path.resolve(part));
   }
 
   const registry = path.join(os.homedir(), ".pan", "projects");
@@ -188,7 +187,7 @@ function findSourcesWithCommand(commandName, startDir = process.cwd()) {
 }
 
 function formatProjectList(matches, commandName) {
-  const lines = [`Lệnh '${commandName}' có ở nhiều nơi:`];
+  const lines = [`Command '${commandName}' is defined in multiple places:`];
   matches.forEach((source, index) => {
     const def = source.commands[commandName];
     const desc = def?.description ? ` — ${def.description}` : "";
@@ -199,7 +198,7 @@ function formatProjectList(matches, commandName) {
     lines.push(`  ${index + 1}. ${label} (${source.root})${desc}`);
   });
   lines.push("");
-  lines.push("Chọn số thứ tự, hoặc chạy lại với --project <tên-repo>.");
+  lines.push("Pick a number, or rerun with --project <repo-name>.");
   return lines.join("\n");
 }
 
@@ -207,8 +206,13 @@ function isBuiltinGitCommand(name) {
   return BUILTIN_GIT_COMMANDS.has(name);
 }
 
+function isBuiltinWorkspaceCommand(name) {
+  return BUILTIN_WORKSPACE_COMMANDS.has(name);
+}
+
 module.exports = {
   BUILTIN_GIT_COMMANDS,
+  BUILTIN_WORKSPACE_COMMANDS,
   PAN_CONFIG_FILE,
   findNearestProjectManifest,
   findNearestWorkspace,
@@ -217,6 +221,7 @@ module.exports = {
   findSourcesWithCommand,
   formatProjectList,
   isBuiltinGitCommand,
+  isBuiltinWorkspaceCommand,
   getCommandDefinition,
   sourceMatchesProject,
 };

package/lib/git/git-clone.js

@@ -10,6 +10,7 @@
 const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
+const { spawnOptions } = require("../../platform");
 const { parseCommonArgs, loadManifestRepos, printCommonOptions } = require("./helpers/cli");
 
 function cloneRepo({ name, url, destination, dryRun }) {
@@ -26,7 +27,7 @@ function cloneRepo({ name, url, destination, dryRun }) {
   }
 
   console.log(`[clone] ${name}: ${url} -> ${destination}`);
-  const result = spawnSync(command[0], command.slice(1), { stdio: "inherit" });
+  const result = spawnSync(command[0], command.slice(1), spawnOptions({ stdio: "inherit" }));
   if (result.status !== 0) {
     console.log(`[warn] ${name}: clone failed, check repo access or url`);
   }

package/lib/git/git-grv.js

@@ -2,7 +2,7 @@
 /*
  * List git remotes (git remote -v) for PAN Stack project repositories.
  *
- * Alias tương đương grv trong oh-my-zsh — hiển thị URL đầy đủ (fetch/push).
+ * oh-my-zsh-style alias for grv — full remote URLs (fetch/push).
  */
 
 const { parseCommonArgs, loadManifestRepos, printCommonOptions } = require("./helpers/cli");
@@ -18,7 +18,7 @@ function printRepoRemotes({ label, destination, dryRun }) {
   console.log(destination);
   const lines = listRemotesVerbose(destination);
   if (lines.length === 0) {
-    console.log("(không có remote)");
+    console.log("(no remotes)");
   } else {
     for (const line of lines) {
       console.log(line);
@@ -45,7 +45,7 @@ function printHelp() {
 List git remotes with full URLs (git remote -v) for each repository.
 
 ${printCommonOptions()}
-  --no-workspace       Skip workspace root (chỉ repo trong manifest)`);
+  --no-workspace       Skip workspace root (manifest repos only)`);
 }
 
 function main() {

package/lib/git/git-gst.js

@@ -2,7 +2,7 @@
 /*
  * Git status for PAN Stack project repositories.
  *
- * Alias tương đương gst trong oh-my-zsh — chạy git status trên workspace + repo con.
+ * oh-my-zsh-style alias for gst — git status on workspace + child repos.
  */
 
 const { parseCommonArgs, loadManifestRepos, printCommonOptions } = require("./helpers/cli");
@@ -38,10 +38,10 @@ function printHelp() {
   console.log(`usage: git-gst.js [--base-dir BASE_DIR] [--dry-run] [--no-workspace] [manifest] [git status args...]
 
 Run git status for workspace root and each repository in the manifest.
-Extra args are forwarded to git status (vd: -s, -sb).
+Extra args are forwarded to git status (e.g. -s, -sb).
 
 ${printCommonOptions()}
-  --no-workspace       Skip workspace root (chỉ repo trong manifest)`);
+  --no-workspace       Skip workspace root (manifest repos only)`);
 }
 
 function main() {

package/lib/git/helpers/cli.js

@@ -72,7 +72,7 @@ function resolveProjectWorkspace({
     if (!found) {
       const label = manifestPath || ".project.yaml";
       throw new Error(
-        `Manifest not found: ${label} (đã tìm từ ${startDir} lên thư mục cha)`
+        `Manifest not found: ${label} (walked up from ${startDir})`
       );
     }
     resolvedManifest = found;
@@ -140,7 +140,7 @@ function printCommonOptions() {
 
 options:
   -h, --help           show this help message and exit
-  --base-dir BASE_DIR  Base directory for relative repo paths. Default: thư mục chứa .project.yaml (walk-up từ cwd nếu cần).
+  --base-dir BASE_DIR  Base directory for relative repo paths. Default: directory containing .project.yaml (walk-up from cwd when needed).
   --dry-run            Print commands only`;
 }
 

package/lib/git/helpers/git.js

@@ -1,6 +1,7 @@
 const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
+const { spawnOptions } = require("../../platform");
 
 function isGitRepo(directory) {
   return fs.existsSync(path.join(directory, ".git"));
@@ -14,7 +15,7 @@ function runGit(gitArgs, { cwd, dryRun, action, name }) {
   }
 
   console.log(`[${action}] ${name}: ${cwd}`);
-  const result = spawnSync(command[0], command.slice(1), { stdio: "inherit", cwd });
+  const result = spawnSync(command[0], command.slice(1), spawnOptions({ stdio: "inherit", cwd }));
   return result.status ?? 1;
 }
 
@@ -31,10 +32,10 @@ function ensureRepoExists({ name, destination }) {
 }
 
 function listRemotesVerbose(directory) {
-  const result = spawnSync("git", ["remote", "-v"], {
+  const result = spawnSync("git", ["remote", "-v"], spawnOptions({
     cwd: directory,
     encoding: "utf8",
-  });
+  }));
   if (result.status !== 0) {
     return [];
   }
@@ -45,10 +46,10 @@ function listRemotesVerbose(directory) {
 }
 
 function runGitStatus(directory, gitArgs = []) {
-  const result = spawnSync("git", ["status", ...gitArgs], {
+  const result = spawnSync("git", ["status", ...gitArgs], spawnOptions({
     cwd: directory,
     stdio: "inherit",
-  });
+  }));
   return result.status ?? 1;
 }
 

package/lib/manifest.js

@@ -323,7 +323,7 @@ function getCommandDefinition(source, commandName, subArg) {
     const target = def.targets[targetName];
     if (!target) {
       const valid = Object.keys(def.targets).join(" | ");
-      throw new Error(`Target hợp lệ cho '${commandName}': ${valid}`);
+      throw new Error(`Valid targets for '${commandName}': ${valid}`);
     }
     return {
       ...target,

package/lib/platform.js

@@ -0,0 +1,140 @@
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const WINDOWS_RESERVED_NAMES = new Set([
+  "CON",
+  "PRN",
+  "AUX",
+  "NUL",
+  "COM1",
+  "COM2",
+  "COM3",
+  "COM4",
+  "COM5",
+  "COM6",
+  "COM7",
+  "COM8",
+  "COM9",
+  "LPT1",
+  "LPT2",
+  "LPT3",
+  "LPT4",
+  "LPT5",
+  "LPT6",
+  "LPT7",
+  "LPT8",
+  "LPT9",
+]);
+
+function isWindows() {
+  return process.platform === "win32";
+}
+
+function splitEnvList(value) {
+  if (!value) {
+    return [];
+  }
+  // On Windows, do not split on ":" — drive letters use "C:".
+  const parts = isWindows() ? value.split(/[;,]/) : value.split(/[:;,]/);
+  return parts.map((part) => part.trim()).filter(Boolean);
+}
+
+function findBash() {
+  const candidates = isWindows()
+    ? [
+        process.env.PAN_GIT_BASH,
+        process.env.PAN_BASH,
+        process.env.GIT_BASH,
+        process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, "Git", "bin", "bash.exe"),
+        process.env["ProgramFiles(x86)"] &&
+          path.join(process.env["ProgramFiles(x86)"], "Git", "bin", "bash.exe"),
+        process.env.LOCALAPPDATA &&
+          path.join(process.env.LOCALAPPDATA, "Programs", "Git", "bin", "bash.exe"),
+      ]
+    : [process.env.PAN_BASH, process.env.BASH, "/usr/bin/bash", "/bin/bash"];
+
+  for (const candidate of candidates.filter(Boolean)) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+/** @deprecated use findBash */
+function findGitBash() {
+  return findBash();
+}
+
+function spawnOptions(extra = {}) {
+  return isWindows() ? { windowsHide: true, ...extra } : extra;
+}
+
+function normalizeShellEnv(env) {
+  if (!isWindows()) {
+    return env;
+  }
+
+  const normalized = { ...env };
+  for (const key of ["PAN_WORKSPACE_ROOT", "PAN_REPO_ROOT", "PAN_PROJECT_ROOT"]) {
+    if (typeof normalized[key] === "string") {
+      normalized[key] = normalized[key].replace(/\\/g, "/");
+    }
+  }
+  return normalized;
+}
+
+function runShellScript(script, { cwd, env, stdio = "inherit" } = {}) {
+  const shellEnv = normalizeShellEnv(env);
+  const bash = findBash();
+
+  if (!bash) {
+    const hint = isWindows()
+      ? "Install Git for Windows (https://git-scm.com/download/win) or set PAN_GIT_BASH / PAN_BASH to bash.exe."
+      : "Install bash or set PAN_BASH to its path.";
+    throw new Error(
+      `Shell commands in .pan.yaml require bash. ${hint} Alternatively, use 'exec' instead of 'shell'.`
+    );
+  }
+
+  return spawnSync(bash, ["-lc", script], spawnOptions({ cwd, env: shellEnv, stdio }));
+}
+
+function runExecLine(execLine, { cwd, env, stdio = "inherit" } = {}) {
+  return spawnSync(
+    execLine,
+    spawnOptions({ cwd, env: normalizeShellEnv(env), stdio, shell: true })
+  );
+}
+
+function validateFolderName(name) {
+  if (!name || !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name)) {
+    throw new Error(
+      "Invalid folder name. Use letters, numbers, dots, hyphens, or underscores."
+    );
+  }
+
+  if (isWindows()) {
+    if (/[<>:"/\\|?*]/.test(name)) {
+      throw new Error("Invalid folder name for Windows (<>:\"/\\|?* are not allowed).");
+    }
+    const base = name.replace(/\.+$/, "").toUpperCase();
+    if (WINDOWS_RESERVED_NAMES.has(base)) {
+      throw new Error(`Invalid folder name for Windows (reserved name: ${base}).`);
+    }
+  }
+}
+
+module.exports = {
+  isWindows,
+  splitEnvList,
+  findBash,
+  findGitBash,
+  spawnOptions,
+  normalizeShellEnv,
+  runShellScript,
+  runExecLine,
+  validateFolderName,
+};

package/lib/run-command.js

@@ -8,10 +8,11 @@ const {
   resolveCommandName,
 } = require("./manifest");
 const { sourceMatchesProject } = require("./discover");
+const { runShellScript, runExecLine, spawnOptions } = require("./platform");
 
 function needDir(dir) {
   if (!fs.existsSync(dir)) {
-    throw new Error(`Chưa có thư mục: ${dir} (chạy 'pan clone' trước?)`);
+    throw new Error(`Directory not found: ${dir} (run 'pan clone' first?)`);
   }
 }
 
@@ -46,12 +47,11 @@ function runExec(source, def, forwardedArgs) {
 
   const execLine = [def.exec, ...forwardedArgs].filter(Boolean).join(" ").trim();
   if (!execLine) {
-    throw new Error("Command thiếu 'exec' hoặc 'shell'.");
+    throw new Error("Command is missing 'exec' or 'shell'.");
   }
 
-  const result = spawnSync(execLine, {
+  const result = runExecLine(execLine, {
     cwd,
-    shell: true,
     stdio: "inherit",
     env: buildPanEnv(source, forwardedArgs),
   });
@@ -65,12 +65,17 @@ function runShell(source, def, forwardedArgs) {
     needDir(cwd);
   }
 
-  const result = spawnSync(def.shell, {
-    cwd,
-    shell: true,
-    stdio: "inherit",
-    env: buildPanEnv(source, forwardedArgs),
-  });
+  let result;
+  try {
+    result = runShellScript(def.shell, {
+      cwd,
+      stdio: "inherit",
+      env: buildPanEnv(source, forwardedArgs),
+    });
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
 
   process.exit(result.status ?? 1);
 }
@@ -88,7 +93,7 @@ function runProjectCommand(source, commandName, args) {
 
   const resolved = getCommandDefinition(source, commandName, subArg);
   if (!resolved) {
-    throw new Error(`Không tìm thấy lệnh '${commandName}' trong ${source.path}`);
+    throw new Error(`Command '${commandName}' not found in ${source.path}`);
   }
 
   if (resolved.shell) {
@@ -101,7 +106,7 @@ function runProjectCommand(source, commandName, args) {
     return;
   }
 
-  throw new Error(`Lệnh '${commandName}' thiếu 'exec' hoặc 'shell' trong ${source.path}`);
+  throw new Error(`Command '${commandName}' is missing 'exec' or 'shell' in ${source.path}`);
 }
 
 function sourceLabel(source) {
@@ -126,11 +131,11 @@ function promptProjectChoice(matches, commandName) {
     });
     console.log("");
 
-    rl.question("Chọn dự án (số): ", (answer) => {
+    rl.question("Pick a project (number): ", (answer) => {
       rl.close();
       const choice = Number.parseInt(answer, 10);
       if (!Number.isFinite(choice) || choice < 1 || choice > matches.length) {
-        reject(new Error("Lựa chọn không hợp lệ."));
+        reject(new Error("Invalid choice."));
         return;
       }
       resolve(matches[choice - 1]);
@@ -149,7 +154,7 @@ async function runWithProjectResolution(
 
   if (matches.length === 0) {
     throw new Error(
-      `Không tìm thấy lệnh '${commandName}' trong bất kỳ .pan.yaml nào.`
+      `Command '${commandName}' not found in any .pan.yaml file.`
     );
   }
 
@@ -158,7 +163,7 @@ async function runWithProjectResolution(
     source = matches.find((item) => sourceMatchesProject(item, projectFlag));
     if (!source) {
       const names = matches.map((item) => sourceLabel(item)).join(", ");
-      throw new Error(`Không tìm thấy dự án '${projectFlag}'. Có: ${names}`);
+      throw new Error(`Project '${projectFlag}' not found. Available: ${names}`);
     }
   } else if (matches.length === 1) {
     source = matches[0];
@@ -176,7 +181,7 @@ async function runWithProjectResolution(
         (item, index) => `${index + 1}. ${sourceLabel(item)} (${item.root})`
       );
       throw new Error(
-        `Lệnh '${commandName}' trùng ở nhiều dự án. Dùng --project <tên>.\n${lines.join("\n")}`
+        `Command '${commandName}' is defined in multiple projects. Use --project <name>.\n${lines.join("\n")}`
       );
     }
   }
@@ -187,13 +192,13 @@ async function runWithProjectResolution(
 function runGitScript(scriptName, args) {
   const scriptPath = path.join(__dirname, "git", scriptName);
   if (!fs.existsSync(scriptPath)) {
-    throw new Error(`Không tìm thấy script: ${scriptPath}`);
+    throw new Error(`Script not found: ${scriptPath}`);
   }
 
-  const child = spawn(process.execPath, [scriptPath, ...args], {
+  const child = spawn(process.execPath, [scriptPath, ...args], spawnOptions({
     stdio: "inherit",
     env: process.env,
-  });
+  }));
 
   child.on("exit", (code) => {
     process.exit(code ?? 1);

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "pan-stack-cli",
-  "version": "0.1.2",
-  "description": "CLI điều phối PAN Stack — git đa repo và lệnh dự án từ .project.yaml",
+  "version": "0.1.4",
+  "description": "PAN Stack CLI — multi-repo git and project commands from .project.yaml",
   "license": "MIT",
   "bin": {
     "pan": "bin/pan.js"
   },
   "files": [
     "bin",
-    "lib"
+    "lib",
+    "templates"
   ],
   "engines": {
     "node": ">=18"

package/templates/workspace/.claude/skills/writing-guidelines/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: writing-guidelines
+description: Review docs/prose for Writing Guidelines compliance. Use when asked to "review my docs", "check writing style", "audit prose", "review docs voice and tone", or "check this page against the writing handbook".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Writing Guidelines
+
+Review files for compliance with Writing Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```text
+https://raw.githubusercontent.com/vercel-labs/writing-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Local Markdown Rules
+
+Also check generated or edited Markdown against local markdownlint conventions:
+
+- Keep at most one blank line between blocks. Do not create multiple consecutive blank lines. This avoids `MD012/no-multiple-blanks`.
+- Use language tags on fenced code blocks.
+- Before finishing edits, scan changed Markdown files for repeated blank lines.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Apply the local Markdown rules above
+5. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.

package/templates/workspace/.codex/skills/writing-guidelines/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: writing-guidelines
+description: Review docs/prose for Writing Guidelines compliance. Use when asked to "review my docs", "check writing style", "audit prose", "review docs voice and tone", or "check this page against the writing handbook".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Writing Guidelines
+
+Review files for compliance with Writing Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```text
+https://raw.githubusercontent.com/vercel-labs/writing-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Local Markdown Rules
+
+Also check generated or edited Markdown against local markdownlint conventions:
+
+- Keep at most one blank line between blocks. Do not create multiple consecutive blank lines. This avoids `MD012/no-multiple-blanks`.
+- Use language tags on fenced code blocks.
+- Before finishing edits, scan changed Markdown files for repeated blank lines.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Apply the local Markdown rules above
+5. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.

package/templates/workspace/.cursor/skills/writing-guidelines/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: writing-guidelines
+description: Review docs/prose for Writing Guidelines compliance. Use when asked to "review my docs", "check writing style", "audit prose", "review docs voice and tone", or "check this page against the writing handbook".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Writing Guidelines
+
+Review files for compliance with Writing Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```text
+https://raw.githubusercontent.com/vercel-labs/writing-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Local Markdown Rules
+
+Also check generated or edited Markdown against local markdownlint conventions:
+
+- Keep at most one blank line between blocks. Do not create multiple consecutive blank lines. This avoids `MD012/no-multiple-blanks`.
+- Use language tags on fenced code blocks.
+- Before finishing edits, scan changed Markdown files for repeated blank lines.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Apply the local Markdown rules above
+5. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.

package/templates/workspace/.pan.yaml

@@ -0,0 +1,25 @@
+# Workspace-level commands. Per-repo commands live in apps/*/.pan.yaml
+commands:
+  install:
+    alias: i
+    description: Install dependencies across cloned repositories
+    shell: |
+      set -euo pipefail
+      root="${PAN_WORKSPACE_ROOT}"
+      for dir in apps/web apps/api; do
+        [[ -d "$root/$dir" ]] || { echo "Missing: $root/$dir (run 'pan clone' first?)" >&2; exit 1; }
+        echo "-> install $dir"
+        (cd "$root/$dir" && npm install)
+      done
+      echo "Done."
+
+  test:
+    default: web
+    description: Run tests (web | api)
+    targets:
+      web:
+        cwd: apps/web
+        exec: npm test
+      api:
+        cwd: apps/api
+        exec: npm test

package/templates/workspace/.project.yaml

@@ -0,0 +1,15 @@
+project: __PROJECT_NAME__
+managed_by: your-team
+
+stack:
+  repo: repo_url_to_be_filled
+
+repositories:
+  - name: bookshop-web
+    description: Customer-facing web application
+    url: repo_url_to_be_filled
+    path: apps/web
+  - name: bookshop-api
+    description: REST API service
+    url: repo_url_to_be_filled
+    path: apps/api

package/templates/workspace/README.md

@@ -0,0 +1,35 @@
+# __PROJECT_NAME__
+
+PAN Stack workspace shell for the Bookshop example project.
+
+This repository is the **coordination layer** — not the product source tree. It holds
+agent skills, workspace manifests, and `pan` commands. Product code lives in the
+repositories listed in `.project.yaml`.
+
+## Layout
+
+```text
+__PROJECT_NAME__/
+  .project.yaml          # Workspace manifest (repository list)
+  .pan.yaml              # Workspace-level pan commands
+  .claude/skills/        # Claude Code skills
+  .cursor/skills/        # Cursor agent skills
+  .codex/skills/         # Codex agent skills
+  apps/
+    web/                 # bookshop-web (after pan clone)
+    api/                 # bookshop-api (after pan clone)
+```
+
+## Quick start
+
+```bash
+# Edit repository URLs in .project.yaml, then:
+pan clone
+pan install
+pan test web
+```
+
+## Agent skills
+
+All three agent folders ship with the shared `writing-guidelines` skill. Add more
+skills under each `.claude`, `.cursor`, and `.codex` directory as your team grows.