minimal-vibe-coding-kit 0.3.0 → 0.4.0

package/.vibekit/skills/path-sensitive-shell-safety/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: path-sensitive-shell-safety
+description: Guardrail workflow for shell changes that use path variables, remote base directories, repo folders, checkout repair, or destructive filesystem commands such as rm, mv, cp, rsync, find -delete, git clean, or git reset.
+argument-hint: "<script path, command, or safety review target>"
+user-invocable: true
+effort: medium
+---
+
+# Path-Sensitive Shell Safety
+
+Use this skill before editing or reviewing shell, deploy, installer, cleanup, or repair logic that builds filesystem paths from variables or touches remote repositories.
+
+Common triggers:
+
+- Path variables such as `remote_base`, `repo_dir`, `repo_folder`, `target_dir`, `backup_dir`, `worktree`, `site`, `app`, or user-entered folder names.
+- Destructive or path-sensitive commands: `rm`, `mv`, `cp -a`, `rsync --delete`, `find -delete`, `docker volume rm`, `git clean`, `git reset`, checkout repair, clone replacement, or symlink-sensitive copy.
+- Git sync that decides which branch or remote checkout will be deployed.
+
+## Safety objective
+
+No empty, unset, broad, symlinked, or unintended path may reach a destructive command. Validate values before joining paths, validate the joined path before use, and validate containment immediately before the command.
+
+## Required workflow
+
+1. Identify the command with the highest blast radius.
+2. List every variable that contributes to its path or repository target.
+3. Classify each variable:
+   - trusted constant;
+   - config value;
+   - remote/server value;
+   - user/operator input;
+   - derived path.
+4. Validate raw inputs before joining:
+   - required and non-empty;
+   - expected shape: absolute base path or safe single folder segment;
+   - no traversal, newlines, glob metacharacters, leading option dash, or control characters;
+   - explicit allowlist for server roots when possible.
+5. Join paths with quoted expansions only. Do not use `eval`.
+6. Canonicalize existing paths with physical resolution (`pwd -P` or `realpath`) before destructive work.
+7. Assert containment:
+   - target is inside the approved base;
+   - target is not `/`, `.`, `..`, `$HOME`, the base root itself, or another broad system directory;
+   - target is not a symlink unless the operation explicitly supports symlinks.
+8. Put the final guard directly next to the dangerous command.
+9. Use command terminators and quoting: `-- "$path"` where supported.
+10. For Git sync, verify expected origin, selected branch policy, fetch success, clean worktree, fast-forward state, and final `HEAD == origin/<branch>` before build/deploy.
+11. Run the repo validation command and AgentShield probe when this changes agent surfaces or automation rules.
+
+## Required outcomes
+
+- A blank branch may follow the documented default-branch fallback policy.
+- An explicit branch must fail if missing; never silently deploy another branch.
+- A blank folder/base value must fail before any `rm`, `mv`, `cp`, `rsync`, `find`, Docker, or Git cleanup command runs.
+- A repair flow may move an unusable checkout to a timestamped backup only after a verified replacement exists.
+- No automatic cleanup should delete backups, locks, runtime data, uploads, volumes, databases, or environment files without separate explicit confirmation.
+
+## Review priority
+
+Use `reviewing-4p-priorities` if triage is needed:
+
+- P0: unsafe path command already caused data loss or can expose/delete secrets in the active environment.
+- P1: unchecked empty/broad variable can reach destructive commands in deploy/repair/install paths.
+- P2: guard exists but misses edge cases such as symlinks, traversal, explicit branch fallback, or wrong origin.
+- P3/P4: documentation clarity or minor naming improvements after the safety invariant is already enforced.
+
+## Reference
+
+Use `references/workflow.md` for copy-ready guard patterns and review checklist.

package/.vibekit/skills/path-sensitive-shell-safety/references/workflow.md

@@ -0,0 +1,127 @@
+# Path-Sensitive Shell Safety Reference
+
+This reference gives reusable guard patterns for shell scripts. Adapt names and allowlists to the repo, but keep the invariant: validate raw input, validate the joined path, then guard immediately before the dangerous command.
+
+## Baseline guard functions
+
+```bash
+die() {
+  printf 'ERROR: %s\n' "$*" >&2
+  exit 1
+}
+
+require_nonempty() {
+  local name="${1:?missing name}"
+  local value="${2-}"
+  [[ -n "$value" ]] || die "$name is required"
+  [[ "$value" != *$'\n'* && "$value" != *$'\r'* ]] || die "$name contains a newline"
+}
+
+validate_abs_base_path() {
+  local name="${1:?missing name}"
+  local value="${2-}"
+  require_nonempty "$name" "$value"
+  [[ "$value" == /* ]] || die "$name must be an absolute path: $value"
+  [[ "$value" != "/" && "$value" != "." && "$value" != ".." ]] || die "$name is too broad: $value"
+  [[ "$value" != *"/../"* && "$value" != *"/./"* && "$value" != *"//"* ]] || die "$name contains unsafe traversal: $value"
+  case "$value" in
+    /bin|/boot|/dev|/etc|/home|/lib|/lib64|/opt|/private|/root|/sbin|/srv|/sys|/tmp|/usr|/var)
+      die "$name points at a broad system directory: $value"
+      ;;
+  esac
+}
+
+validate_folder_segment() {
+  local name="${1:?missing name}"
+  local value="${2-}"
+  require_nonempty "$name" "$value"
+  [[ "$value" != -* ]] || die "$name must not start with '-': $value"
+  [[ "$value" != "." && "$value" != ".." ]] || die "$name is unsafe: $value"
+  [[ "$value" != */* && "$value" != *\\* ]] || die "$name must be one folder segment: $value"
+  [[ "$value" =~ ^[A-Za-z0-9._#@+=:-]+$ ]] || die "$name contains unsupported characters: $value"
+}
+
+join_child_path() {
+  local base="${1:?missing base}"
+  local child="${2:?missing child}"
+  printf '%s/%s\n' "${base%/}" "$child"
+}
+```
+
+## Containment guard
+
+```bash
+canonical_existing_dir() {
+  local path_value="${1:?missing path}"
+  [[ -d "$path_value" ]] || die "not a directory: $path_value"
+  [[ ! -L "$path_value" ]] || die "refusing symlink directory: $path_value"
+  (cd -P -- "$path_value" && pwd) || die "cannot resolve directory: $path_value"
+}
+
+assert_child_under_parent() {
+  local parent="${1:?missing parent}"
+  local child="${2:?missing child}"
+  [[ "$child" != "$parent" ]] || die "refusing to operate on parent directory itself: $child"
+  case "$child" in
+    "$parent"/*) ;;
+    *) die "path escapes parent: child=$child parent=$parent" ;;
+  esac
+}
+```
+
+## Safer remove wrapper
+
+Use a wrapper instead of inline deletion when a path contains variables.
+
+```bash
+safe_rm_rf_dir() {
+  local label="${1:?missing label}"
+  local target="${2-}"
+  local allowed_parent="${3-}"
+
+  validate_abs_base_path "$label target" "$target"
+  validate_abs_base_path "$label allowed parent" "$allowed_parent"
+
+  [[ -d "$target" ]] || die "$label target is not an existing directory: $target"
+  [[ ! -L "$target" ]] || die "$label target is a symlink: $target"
+
+  local parent_real
+  parent_real="$(canonical_existing_dir "$allowed_parent")"
+
+  local target_real
+  target_real="$(canonical_existing_dir "$target")"
+
+  assert_child_under_parent "$parent_real" "$target_real"
+  rm -rf -- "$target_real"
+}
+```
+
+Never call the wrapper with a broad parent such as `/`, `/opt`, `/var`, `/tmp`, or `$HOME`. Use the narrowest app-owned parent.
+
+## Git sync guard checklist
+
+- Validate the checkout directory is inside the approved app base.
+- Validate the origin URL or host matches the expected repository.
+- Fetch with bounded timeout and non-interactive credentials.
+- Explicit branch:
+  - require the exact remote branch;
+  - fail with an actionable message if it is missing.
+- Blank branch:
+  - current valid upstream;
+  - remote default branch;
+  - `main`;
+  - `master`.
+- Refuse dirty, local-ahead, or diverged worktrees unless the operator chooses a guided repair command.
+- After sync, verify `git rev-parse HEAD` equals `git rev-parse "origin/<branch>"`.
+- Build or deploy only after the equality check passes.
+
+## Review checklist
+
+- Are all path variables checked with `[[ -n "$value" ]]` or a stronger helper before use?
+- Are folder names validated as segments before joining?
+- Is the final path canonicalized or otherwise proven inside the base?
+- Is the destructive command adjacent to its guard?
+- Does the command use quoted expansions and `--` where available?
+- Does the code fail closed for missing explicit branches?
+- Does repair preserve runtime data and keep backups instead of deleting them?
+- Does validation cover empty values, traversal, symlink, wrong origin, dirty checkout, branch with `#`, and missing branch?

package/{skills → .vibekit/skills}/vibekit-init/SKILL.md

@@ -11,15 +11,15 @@ Initialize the kit safely.
 
 ## Required behavior
 
-1. Print the requirements checklist from `FIRST_TIME_INIT.md`.
+1. Print the requirements checklist from `.vibekit/init/FIRST_TIME_INIT.md`.
 2. Run or emulate detection, including repo-specific conventions, project mode, and PRD presence:
 
 ```bash
-node .vbkit-scripts/init-backbone.mjs . --propose
+node .vibekit/scripts/init-backbone.mjs . --propose
 ```
 
 3. Run the project-understanding step below.
-4. Propose a unified diff for `backbone.yml`, its `conventions` rules, managed blocks, and any new `.vbkit-docs/PRD.md`.
+4. Propose a unified diff for `backbone.yml`, its `conventions` rules, managed blocks, and any new `.vibekit/docs/PRD.md`.
 5. Ask: `Apply this proposed backbone and convention rules? Reply yes, edit, or abort.`
 6. Write only after explicit `yes`.
 7. Validate after writing.
@@ -29,9 +29,9 @@ node .vbkit-scripts/init-backbone.mjs . --propose
 Detection reports `project.mode` (`greenfield` = no source yet, `brownfield` = existing code) and whether a PRD exists.
 
 - Always offer a short interview, regardless of whether docs already exist: what the project is and who it is for, the core problem and primary focus now, what success looks like, key constraints/non-goals, and (brownfield) which area to improve first.
-- If no PRD is found, propose creating `.vbkit-docs/PRD.md` from `.vbkit-docs/templates/PRD_TEMPLATE.md` using the answers, and set `project.prd` to that path.
+- If no PRD is found, propose creating `.vibekit/docs/PRD.md` from `.vibekit/docs/templates/PRD_TEMPLATE.md` using the answers, and set `project.prd` to that path.
 - If a PRD exists, read it, link it in `project.prd`, and offer to refresh it without overwriting unapproved content.
-- Keep the PRD short; it captures intent, not a full spec. Record domain terms in `.vbkit-docs/CONTEXT.md` (scaffold from `.vbkit-docs/templates/CONTEXT_TEMPLATE.md`) and link it in `project.context`.
+- Keep the PRD short; it captures intent, not a full spec. Record domain terms in `.vibekit/docs/CONTEXT.md` (scaffold from `.vibekit/docs/templates/CONTEXT_TEMPLATE.md`) and link it in `project.context`.
 
 ## Convention detection
 
@@ -49,4 +49,4 @@ Detection reports `project.mode` (`greenfield` = no source yet, `brownfield` = e
 
 ## Completion
 
-Report initialized status, validation command, validation result, PRD path, and next recommended skill. Once the user confirms setup is complete, offer graduation (`node .vbkit-scripts/vibekit-finalize.mjs . --propose`) to move one-time bootstrap files into the cleanup folder.
+Report initialized status, validation command, validation result, PRD path, and next recommended skill. Once the user confirms setup is complete, offer graduation (`node .vibekit/scripts/vibekit-finalize.mjs . --propose`) to move one-time bootstrap files into the cleanup folder.

package/AGENTS.md

@@ -8,7 +8,7 @@ Shared instructions for Claude, Cursor, Codex, and other coding agents.
 ### Source of truth
 
 - Read `backbone.yml` before changing code.
-- If `meta.template_status` is `uninitialized`, follow `FIRST_TIME_INIT.md` and wait for approval before writing.
+- If `meta.template_status` is `uninitialized`, follow `.vibekit/init/FIRST_TIME_INIT.md` and wait for approval before writing.
 - After init, follow the `conventions` rules in `backbone.yml`; ask before changing broad project patterns.
 - Prefer concise root instructions. Put long procedures in skills and docs.
 
@@ -33,13 +33,16 @@ Track every loop in `/tmp/design-{project_slug}.md`. Each loop entry must includ
 - Never print full secrets.
 - Do not run untrusted hooks, MCP servers, deploy scripts, package lifecycle scripts, migrations, or destructive shell commands just to inspect a repo.
 - Do not modify protected paths from `backbone.yml` without explicit approval.
-- If a task changes agent surfaces (`CLAUDE.md`, `AGENTS.md`, `.claude/**`, `.cursor/**`, `.agents/**`, `.codex-plugin/**`, `skills/**`, `.vbkit-commands/**`, `.vbkit-scripts/**`, hooks, MCP config), run the AgentShield probe or explain why it was skipped.
+- Before editing or approving shell/deploy/installer/repair logic that uses path variables or destructive commands (`rm`, `mv`, `cp -a`, `rsync --delete`, `find -delete`, `git clean`, checkout replacement), use `path-sensitive-shell-safety` and prove base/folder/repo values are non-empty, contained, quoted, and not broad system paths.
+- If a task changes agent surfaces (`CLAUDE.md`, `AGENTS.md`, `.claude/**`, `.cursor/**`, `.agents/**`, `.codex-plugin/**`, `.vibekit/skills/**`, `.vibekit/commands/**`, `.vibekit/scripts/**`, hooks, MCP config), run the AgentShield probe or explain why it was skipped.
 
 ### Skills to prefer
 
 - `vibekit-init`: first-time init and repair.
+- `parallel-analysis`: fan out 2-5 read-only analysis lanes for repo-wide questions, large diff reviews, or consistency audits, then merge with a verification pass.
 - `autoresearch-coding`: metric-driven experiment loop.
 - `agentshield-security-review`: agent-surface security review.
+- `path-sensitive-shell-safety`: validate remote base paths, repo folders, branch sync, and destructive shell commands before edits land.
 - `daily-workflow-curator`: daily proposal for improving rules, skills, workflows, and docs.
 - `visual-design-loop`: screenshot-driven UI polish loop.
 

package/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
-## Unreleased
+## 0.4.0 — 2026-07-16
+
+- Trimmed the end-user install payload: `mvck install`/`update` no longer copy kit-maintainer files (`test-install.mjs`, `pack-dry-run.mjs`, `.vibekit/docs/RESEARCH_NOTES.md`, `.vibekit/docs/AUTORESEARCH_LEDGER.md`); `validate-kit` requires them only in the kit source repo.
+- `mvck install`/`update` now reject unknown `--profile` values instead of silently installing shared files only.
+- `install.sh` no longer misreads a leading flag as the target directory.
+- Fixed stale pre-0.4 path references: `.codex-plugin/plugin.json` now points at `./.vibekit/skills/` (version synced to the kit), the AgentShield probe scans `.vibekit/skills`/`.claude/skills`/`.cursor/skills`, and autoresearch/agentshield skill docs use `.vibekit/skills` in editable-path examples.
+- Added `parallel-analysis` to the AGENTS.md "Skills to prefer" list.
+- Broadened CI PR path filters to cover `install.sh`, `install.ps1`, `.vibekit/init/**`, and `.vibekit/docs/**`.
+- Rewrote `README.md` and `README.vi.md`: short Quick Start, end-user install topology, day-to-day guide, full commands/skills tables (now including `/vibe-finalize` and `parallel-analysis`), and an Advanced section; version badge synced to the package version.
+
+- BREAKING: consolidated all kit-owned files into a single `.vibekit/` folder — `.vbkit-scripts/` -> `.vibekit/scripts/`, `.vbkit-commands/` -> `.vibekit/commands/`, `.vbkit-docs/` -> `.vibekit/docs/`, `skills/` -> `.vibekit/skills/`, and one-time onboarding files (`FIRST_TIME_INIT.md`, `FIRST_PROMPT.md`, `CLAUDE-template.md`, `PUSH_TO_GITHUB.md`) -> `.vibekit/init/`. User repos now get one kit folder plus the harness surfaces (`.claude/`, `.cursor/`, `.agents/`, `.codex/`, `.codex-plugin/`) and root entrypoints (`backbone.yml`, `AGENTS.md`, `CLAUDE.md`). `mvck install`/`update` print an advisory legacy-layout note (never auto-delete) when pre-0.4 paths are found.
+- Added `parallel-analysis` skill (shared + Claude/Cursor/Codex mirrors): fan out 2-5 read-only analysis lanes via Cursor CLI Composer (recommended), Claude subagents, or Codex CLI, then merge and verify findings; first use asks for the provider/model once and persists it to `.vibekit/parallel-analysis.json`.
 
 - Added `memento` skill (cross-session `MEMENTO.md` working memory) across shared, Claude, Codex, and Cursor surfaces.
 - Added `coding-level` skill (explanation register 0=ELI5 … 5=expert peer, with per-level reference personas) across shared, Claude, Codex, and Cursor surfaces.
@@ -11,7 +22,7 @@
 - Fixed `mvck init|validate|daily` delegation so flags are preserved when target is omitted.
 - Added install/idempotency tests with temporary clean and existing repos.
 - Added `mvck doctor` with optional `VIBE_REPORT.md` generation.
-- Added dependency-free `backbone.yml` schema validation and `.vbkit-docs/backbone.schema.json`.
+- Added dependency-free `backbone.yml` schema validation and `.vibekit/docs/backbone.schema.json`.
 - Added a portable Node wrapper for the AgentShield probe.
 - Added syntax checks, `npm test`, CI Node 18/20/22 matrix, and package dry-run verification.
 - Added release safety docs and Dependabot config.

package/CONTRIBUTING.md

@@ -15,10 +15,10 @@ npm run pack:dry-run
 ## Change guidelines
 
 - Preserve existing project files during install; prefer managed blocks for shared instructions.
-- Keep root instructions concise and move long procedures into `skills/` or `.vbkit-docs/`.
+- Keep root instructions concise and move long procedures into `.vibekit/skills/` or `.vibekit/docs/`.
 - Do not add package lifecycle scripts, hooks, MCP servers, migrations, or deploy steps that run during install.
-- Update `.vbkit-docs/backbone.schema.json` and `.vbkit-scripts/validate-kit.mjs` together when `backbone.yml` changes.
-- Add an install/idempotency test when changing `.vbkit-scripts/mvck.mjs`.
+- Update `.vibekit/docs/backbone.schema.json` and `.vibekit/scripts/validate-kit.mjs` together when `backbone.yml` changes.
+- Add an install/idempotency test when changing `.vibekit/scripts/mvck.mjs`.
 
 ## Pull request checklist