minimal-vibe-coding-kit 0.3.0 → 0.4.0

package/.cursor/skills/parallel-analysis/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: parallel-analysis
+description: Fan out 2-5 independent read-only analysis lanes across the repo using your configured executor (Cursor CLI Composer, Claude subagents, or Codex CLI), then merge the lane reports and verify them with a refutation pass. Use for repo-wide questions, large uncommitted-diff reviews, multi-doc reading, impact analysis, or consistency audits. On first use it asks which provider/model to use and saves the answer so it never asks again.
+argument-hint: "<analysis question, diff, or review target>"
+user-invocable: true
+effort: medium
+---
+
+# Parallel Analysis (Multi-Agent Fan-Out)
+
+Split a large analysis into independent read-only lanes, run them concurrently
+with the configured executor, merge the lane reports, and verify merged claims
+with a skeptical refutation pass. One round of parallel lanes replaces slow
+serial reading; the verification lane replaces manual double-checking.
+
+This skill is project-agnostic: it works in any repo where the kit is
+installed, using that repo's `backbone.yml` (if present) for boundaries.
+
+## Best Use
+
+- Repo-wide questions ("where is X handled, what depends on Y").
+- Reviewing a large uncommitted diff by concern (backend vs frontend vs i18n
+  vs scripts).
+- Reading several large docs, plans, or reference trees at once.
+- Pre-change impact analysis across packages/apps listed in `backbone.yml`
+  `paths.apps`.
+- Consistency audits (docs vs code, rules vs skills, config vs actual layout).
+
+Do NOT use for single-file questions or quick lookups; direct reads are faster.
+
+## Executor Setup (first use only)
+
+Lane execution is delegated to ONE configured executor. The choice is stored
+in `.vibekit/parallel-analysis.json`; while that file exists and its preflight
+passes, NEVER ask again.
+
+1. **If `.vibekit/parallel-analysis.json` exists**: read it, run the matching
+   preflight below, and proceed silently on success. If preflight fails
+   (binary missing, logged out), tell the user what broke, offer to re-run
+   setup, and update the file with their answer.
+2. **If it does not exist**: detect what is available, then ask the user ONE
+   question — "Which provider should run parallel analysis lanes?" — using the
+   harness-native prompt (AskUserQuestion in Claude Code; a plain chat
+   question in Cursor/Codex). Offer, in this order:
+   - **Cursor CLI + Composer 2.5 Fast (recommended)** — fastest lane executor;
+     requires `cursor-agent` installed and logged in.
+   - **Claude subagents** — no extra install; lanes run as read-only Claude
+     Code subagents (Explore/general-purpose). Choose this automatically if
+     the user declines external CLIs.
+   - **Codex CLI** — lanes run via `codex exec` in a read-only sandbox with
+     the best available Codex model.
+3. **Resolve the model** for the chosen provider (see per-executor notes),
+   confirm the resolved value in one line, and write the config file. Include
+   a fallback executor so lanes still run when the primary is unavailable.
+
+### Preflights and model resolution
+
+- `cursor-cli`: `cursor-agent status` must report logged in (otherwise the
+  user runs `cursor-agent login` once). Resolve the model with
+  `cursor-agent --list-models` and prefer the Composer 2.5 fast variant
+  (e.g. `composer-2.5-fast`); if absent, use the newest Composer model and
+  record what was picked.
+- `claude-subagents`: available whenever running inside Claude Code; no
+  binary needed. Use read-only subagent types only.
+- `codex-cli`: `codex --version` must succeed. Use the CLI's default/best
+  coding model unless the user names one; record the resolved model.
+
+### Config file — `.vibekit/parallel-analysis.json`
+
+```json
+{
+  "executor": "cursor-cli",
+  "model": "composer-2.5-fast",
+  "fallback": "claude-subagents",
+  "configuredAt": "2026-07-16T07:30:00Z"
+}
+```
+
+`executor` is one of `cursor-cli` | `claude-subagents` | `codex-cli`. The file
+is local state (gitignored by default); a team may commit it deliberately to
+share a default. To change the choice later, delete the file or ask for
+"parallel-analysis setup" again.
+
+## Running a lane (per executor)
+
+Every lane is READ-ONLY: search, read, summarize — never edit files, execute
+project binaries, run hooks, or trigger installs/deploys/migrations.
+
+- `cursor-cli`:
+
+  ```sh
+  cursor-agent -p --mode ask --output-format text \
+    --model "<configured-model>" \
+    --workspace "<repo-root>" \
+    "<lane brief>"
+  ```
+
+  Never pass `--force` or `--yolo`; `--mode ask` keeps Composer read-only.
+  One workspace per lane; a question spanning multiple repos becomes one lane
+  per repo.
+- `claude-subagents`: launch each lane as a read-only subagent with the lane
+  brief as its prompt, all lanes in ONE message so they run concurrently.
+- `codex-cli`:
+
+  ```sh
+  codex exec --sandbox read-only -C "<repo-root>" "<lane brief>"
+  ```
+
+If the harness cannot run lanes concurrently (plain CLI loop), run them
+back-to-back without changing the briefs — merge and verification stay the
+same.
+
+## Workflow
+
+1. **Scope.** State the question in one sentence. Split it into 2-5 lanes that
+   are independent of each other (by directory, package, concern, or doc set).
+   If lanes would depend on each other's output, merge them or run two rounds.
+2. **Brief.** Give each lane a numbered brief: exact paths, the questions to
+   answer, and the required return format ("facts only, numbered sections,
+   findings as `file:line — issue — why it matters`").
+3. **Launch all lanes at once** with the configured executor.
+4. **Prepare while waiting.** Build the merge skeleton; do not duplicate lane
+   work.
+5. **Merge.** Combine lane reports into one findings list. Mark conflicts
+   between lanes and unknowns explicitly — never average away a disagreement.
+6. **Verify.** Run one verification lane that receives the merged claims (not
+   the reasoning) with the instruction: "Default-skeptical: confirm or refute
+   each claim against the repo with file:line evidence." Drop or re-investigate
+   every refuted claim; never silently keep one.
+7. **Deliver.** Report merged findings, what was verified, and remaining
+   unknowns. For issue triage, classify surviving findings with the
+   `reviewing-4p-priorities` skill (P0-P4). Decisions and edits stay in the
+   main session under the repo's normal review rules.
+
+## Lane brief template
+
+```text
+Lane <n>: <one-line purpose>
+Workspace: <repo root>
+Paths: <exact dirs/files>
+Read-only. Do not modify anything or execute binaries/scripts.
+Questions:
+1. <specific question>
+2. <specific question>
+Return: numbered sections matching the questions, facts only,
+findings as file:line — issue — why it matters.
+```
+
+## Guardrails
+
+- 2-5 lanes per round; needing more means the question is under-scoped.
+- Lanes are read-only; only the main session edits files. Agent-surface edits
+  (`backbone.yml`, `AGENTS.md`, `CLAUDE.md`, `.claude/**`, `.cursor/**`,
+  `.agents/**`, `.codex/**`, kit skills/commands) additionally require the
+  `agentshield-security-review` skill afterwards.
+- Respect `backbone.yml` `policy.protected_paths` in every lane brief.
+- Never put secrets in lane briefs or executor prompts: no `.env*` contents,
+  credentials, tokens, private keys, or customer data.
+- This skill produces analysis, not decisions; a lane may not conclude
+  "therefore change X" without main-session review.

package/.cursor/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/.cursor/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/.vibekit/commands/vibe-finalize.md

@@ -0,0 +1,3 @@
+# vibe-finalize
+
+Graduate this project once init and the first prompt are complete. Run `node .vibekit/scripts/vibekit-finalize.mjs . --propose` to preview, then `--write --yes` to move one-time bootstrap files (.vibekit/init/FIRST_TIME_INIT.md, .vibekit/init/FIRST_PROMPT.md, .vibekit/init/PUSH_TO_GITHUB.md, .vibekit/init/CLAUDE-template.md) into `_vibekit-cleanup/` for deletion. It refuses to run on the kit source repo and is reversible with `--restore --write`.

package/{.vbkit-docs → .vibekit/docs}/AUTORESEARCH_LEDGER.md

@@ -4,8 +4,8 @@ This file summarizes the improvement loop used to build and maintain the enhance
 
 | Experiment | Metric | Result | Kept reason |
 |---|---:|---|---|
-| Baseline review | `node .vbkit-scripts/validate-kit.mjs .` -> `171/0f/0w` | keep | established current kit health before new edits |
-| Package manifest coverage | `node .vbkit-scripts/validate-kit.mjs .` -> `215/0f/0w` | keep | validates npm bin targets and shipped `files` entries |
-| Codex and CI coverage | `node .vbkit-scripts/validate-kit.mjs .` -> `221/0f/0w` | keep | validates Codex support files and core CI workflow commands |
+| Baseline review | `node .vibekit/scripts/validate-kit.mjs .` -> `171/0f/0w` | keep | established current kit health before new edits |
+| Package manifest coverage | `node .vibekit/scripts/validate-kit.mjs .` -> `215/0f/0w` | keep | validates npm bin targets and shipped `files` entries |
+| Codex and CI coverage | `node .vibekit/scripts/validate-kit.mjs .` -> `221/0f/0w` | keep | validates Codex support files and core CI workflow commands |
 
 Final validation results for each run are recorded in `.autoresearch/logs/` and summarized in `results.tsv`.

package/{.vbkit-docs → .vibekit/docs}/BACKBONE_REFERENCE.md

@@ -17,7 +17,7 @@
 
 `meta.template_status` is the durable init flag.
 
-- `uninitialized`: agent must run `FIRST_TIME_INIT.md`.
+- `uninitialized`: agent must run `.vibekit/init/FIRST_TIME_INIT.md`.
 - `initialized`: agent skips init and proceeds.
 
 `.vibekit/INIT_DONE` is a local cache only. It helps prevent same-machine repeat init, but does not need to be committed.

package/{.vbkit-docs → .vibekit/docs}/INSTALL.md

@@ -9,7 +9,7 @@
 ## Node install
 
 ```bash
-node .vbkit-scripts/mvck.mjs install /path/to/project --profile all
+node .vibekit/scripts/mvck.mjs install /path/to/project --profile all
 ```
 
 Profiles:
@@ -31,8 +31,8 @@ The installer:
 Preview without writing:
 
 ```bash
-node .vbkit-scripts/mvck.mjs install /path/to/project --profile all --dry-run
-node .vbkit-scripts/mvck.mjs install /path/to/project --profile all --dry-run --json
+node .vibekit/scripts/mvck.mjs install /path/to/project --profile all --dry-run
+node .vibekit/scripts/mvck.mjs install /path/to/project --profile all --dry-run --json
 ```
 
 ## Update an existing project
@@ -42,12 +42,12 @@ When a newer kit version ships, refresh kit-owned files without touching user-ow
 ```bash
 npx --yes minimal-vibe-coding-kit@latest update .
 # or from a local kit clone:
-node /path/to/kit/.vbkit-scripts/mvck.mjs update /path/to/project
+node /path/to/kit/.vibekit/scripts/mvck.mjs update /path/to/project
 ```
 
 The updater:
 
-- refreshes kit-owned surfaces (`skills/`, `.vbkit-commands/`, `.vbkit-scripts/`, `.vbkit-docs/`, and the `.claude/`, `.cursor/`, `.agents/`, `.codex*` mirrors) and adds any new kit skills;
+- refreshes kit-owned surfaces (`.vibekit/skills/`, `.vibekit/commands/`, `.vibekit/scripts/`, `.vibekit/docs/`, and the `.claude/`, `.cursor/`, `.agents/`, `.codex*` mirrors) and adds any new kit skills;
 - never overwrites `backbone.yml`, `CLAUDE.md`, `AGENTS.md` content outside the managed block, or `settings.json` files — those are seeded only if missing;
 - backs up every replaced kit file to `.vibekit/update-backup/<timestamp>/` (disable with `--no-backup`);
 - never deletes files you added, and skips re-seeding one-time files after `mvck finalize`;
@@ -60,30 +60,30 @@ npx --yes minimal-vibe-coding-kit@latest update . --dry-run
 npx --yes minimal-vibe-coding-kit@latest update . --dry-run --json
 ```
 
-Note: run the updater from a newer kit (npx or a local clone), not via the project's own `.vbkit-scripts/mvck.mjs` copy — source and target would be the same files.
+Note: run the updater from a newer kit (npx or a local clone), not via the project's own `.vibekit/scripts/mvck.mjs` copy — source and target would be the same files.
 
 ## After install
 
-Paste the universal prompt from `FIRST_PROMPT.md`, or run:
+Paste the universal prompt from `.vibekit/init/FIRST_PROMPT.md`, or run:
 
 ```bash
-node .vbkit-scripts/init-backbone.mjs . --propose
+node .vibekit/scripts/init-backbone.mjs . --propose
 ```
 
 Use a preset when you already know the target stack:
 
 ```bash
-node .vbkit-scripts/mvck.mjs init . --preset nextjs --propose
-node .vbkit-scripts/mvck.mjs init . --preset wordpress --propose
-node .vbkit-scripts/mvck.mjs init . --preset python --propose
-node .vbkit-scripts/mvck.mjs init . --preset laravel --propose
-node .vbkit-scripts/mvck.mjs init . --preset docker --propose
+node .vibekit/scripts/mvck.mjs init . --preset nextjs --propose
+node .vibekit/scripts/mvck.mjs init . --preset wordpress --propose
+node .vibekit/scripts/mvck.mjs init . --preset python --propose
+node .vibekit/scripts/mvck.mjs init . --preset laravel --propose
+node .vibekit/scripts/mvck.mjs init . --preset docker --propose
 ```
 
 Review the proposal. After approval:
 
 ```bash
-node .vbkit-scripts/init-backbone.mjs . --write --yes
+node .vibekit/scripts/init-backbone.mjs . --write --yes
 ```
 
 ## Doctor
@@ -91,13 +91,13 @@ node .vbkit-scripts/init-backbone.mjs . --write --yes
 Run a read-only health check after install:
 
 ```bash
-node .vbkit-scripts/mvck.mjs doctor .
+node .vibekit/scripts/mvck.mjs doctor .
 ```
 
 Generate a handoff report:
 
 ```bash
-node .vbkit-scripts/mvck.mjs doctor . --write-report
+node .vibekit/scripts/mvck.mjs doctor . --write-report
 ```
 
 ## Native reasoning skills

package/{.vbkit-docs → .vibekit/docs}/RESEARCH_NOTES.md

@@ -14,7 +14,7 @@ The kit follows these design decisions:
 
 ```text
 Goal: improve Minimal Vibe Coding Kit quality.
-Metric command: node .vbkit-scripts/validate-kit.mjs .
+Metric command: node .vibekit/scripts/validate-kit.mjs .
 Direction: higher pass count and zero failures.
 Editable paths: docs, scripts, skills, commands, .claude, .cursor, .agents, .codex-plugin, .github, root templates.
 Protected paths: .git, .env*, node_modules, vendor packages, secrets, lockfiles.

package/{.vbkit-docs → .vibekit/docs}/SECURITY_MODEL.md

@@ -6,7 +6,7 @@ Review these before merging changes:
 
 - `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`
 - `.claude/**`, `.cursor/**`, `.agents/**`, `.codex-plugin/**`
-- `skills/**`, `.vbkit-commands/**`, `.vbkit-scripts/**`, `hooks/**`
+- `.vibekit/skills/**`, `.vibekit/commands/**`, `.vibekit/scripts/**`, `hooks/**`
 - `.mcp.json`, `mcp.json`, `mcp-configs/**`
 - installer scripts and CI workflows
 
@@ -15,7 +15,7 @@ Review these before merging changes:
 Read-only probe:
 
 ```bash
-node .vbkit-scripts/agentshield-probe.mjs .
+node .vibekit/scripts/agentshield-probe.mjs .
 ```
 
 Full scanner when available:

package/{.vbkit-docs → .vibekit/docs}/TOOLING_GUIDE.md

@@ -2,7 +2,7 @@
 
 ## Claude Code
 
-Use root `CLAUDE.md` plus project skills in `.claude/skills/`. Keep long instructions out of `CLAUDE.md` and in skills. The kit provides shims that point to canonical shared skills under `skills/`.
+Use root `CLAUDE.md` plus project skills in `.claude/skills/`. Keep long instructions out of `CLAUDE.md` and in skills. The kit provides shims that point to canonical shared skills under `.vibekit/skills/`.
 
 ## Cursor
 
@@ -14,7 +14,7 @@ Use `AGENTS.md` for repo instructions and `.agents/skills/*/SKILL.md` for skills
 
 ## Shared skill strategy
 
-Canonical skill bodies live in `skills/<skill-name>/`. Harness-specific folders contain small shims:
+Canonical skill bodies live in `.vibekit/skills/<skill-name>/`. Harness-specific folders contain small shims:
 
 - `.claude/skills/<skill-name>/SKILL.md`
 - `.agents/skills/<skill-name>/SKILL.md`

package/{.vbkit-docs → .vibekit/docs}/templates/CONTEXT_TEMPLATE.md

@@ -43,5 +43,5 @@ Non-obvious things that have surprised people. Save the next agent the debugging
 
 ---
 
-Related: `.vbkit-docs/PRD.md` (intent and focus) and `backbone.yml` (project map, commands,
+Related: `.vibekit/docs/PRD.md` (intent and focus) and `backbone.yml` (project map, commands,
 protected paths). Link `project.context` in `backbone.yml` to this file.

package/{.vbkit-docs → .vibekit/docs}/templates/PRD_TEMPLATE.md

@@ -44,5 +44,5 @@ If existing code: which module, surface, or flow are we improving first, and why
 
 ---
 
-Linked context: see `.vbkit-docs/CONTEXT.md` for domain terminology and `backbone.yml`
+Linked context: see `.vibekit/docs/CONTEXT.md` for domain terminology and `backbone.yml`
 for the project map (`project.mode`, `project.prd`, conventions, commands).

package/{CLAUDE-template.md → .vibekit/init/CLAUDE-template.md}

@@ -7,7 +7,7 @@ This file is intentionally small. Shared rules live in `AGENTS.md`, project fact
 ## Startup
 
 1. Read `backbone.yml`.
-2. If `meta.template_status` is `uninitialized`, follow `FIRST_TIME_INIT.md` before other work.
+2. If `meta.template_status` is `uninitialized`, follow `.vibekit/init/FIRST_TIME_INIT.md` before other work.
 3. If initialized, follow `backbone.yml` `conventions` and continue with the user's task.
 
 ## Useful skills

package/{FIRST_PROMPT.md → .vibekit/init/FIRST_PROMPT.md}

@@ -5,7 +5,7 @@ Use one of these after installing the kit into a project.
 ## Universal first prompt
 
 ```text
-Read FIRST_TIME_INIT.md and initialize this repo with Minimal Vibe Coding Kit.
+Read .vibekit/init/FIRST_TIME_INIT.md and initialize this repo with Minimal Vibe Coding Kit.
 First print the requirements you will check. Then run detection, propose one diff for backbone.yml and managed instruction blocks, and wait for my yes before writing.
 Include inferred project conventions for naming, architecture, resources, localization, generated definitions, and per-app/package differences.
 After approval, write the files, run validation, and summarize what changed.
@@ -20,13 +20,13 @@ Use /init-vibe. Keep CLAUDE.md short. Import shared AGENTS.md. Do not overwrite
 ## Cursor
 
 ```text
-Read FIRST_TIME_INIT.md and .cursor/rules. Initialize backbone.yml. Do not replace existing Cursor rules; add missing Minimal Vibe Coding Kit rules only.
+Read .vibekit/init/FIRST_TIME_INIT.md and .cursor/rules. Initialize backbone.yml. Do not replace existing Cursor rules; add missing Minimal Vibe Coding Kit rules only.
 ```
 
 ## Codex
 
 ```text
-Read AGENTS.md and FIRST_TIME_INIT.md. Use the vibekit-init skill if available. Initialize backbone.yml, include inferred project conventions, keep AGENTS.md concise, and wait for approval before writing.
+Read AGENTS.md and .vibekit/init/FIRST_TIME_INIT.md. Use the vibekit-init skill if available. Initialize backbone.yml, include inferred project conventions, keep AGENTS.md concise, and wait for approval before writing.
 ```
 
 ## Autoresearch improvement loop for this kit
@@ -34,9 +34,9 @@ Read AGENTS.md and FIRST_TIME_INIT.md. Use the vibekit-init skill if available.
 ```text
 Use the autoresearch-coding skill.
 Goal: improve this Minimal Vibe Coding Kit for existing projects in any language.
-Metric command: node .vbkit-scripts/validate-kit.mjs .
+Metric command: node .vibekit/scripts/validate-kit.mjs .
 Direction: higher.
-Editable paths: README.md .vbkit-docs .vbkit-scripts skills .vbkit-commands .claude .cursor .agents .codex-plugin .github backbone.yml AGENTS.md CLAUDE-template.md FIRST_TIME_INIT.md package.json install.sh install.ps1.
+Editable paths: README.md .vibekit/docs .vibekit/scripts skills .vibekit/commands .claude .cursor .agents .codex-plugin .github backbone.yml AGENTS.md .vibekit/init/CLAUDE-template.md .vibekit/init/FIRST_TIME_INIT.md package.json install.sh install.ps1.
 Protected paths: .git .env* node_modules vendor secrets lockfiles.
 Budget: 3.
 ```
@@ -50,5 +50,5 @@ Use the agentshield-security-review skill. Run the read-only probe first. Then,
 ## Daily improvement prompt
 
 ```text
-Use the daily-workflow-curator skill. Run node .vbkit-scripts/daily-enhance.mjs . --write-report and node .vbkit-scripts/validate-kit.mjs . Then propose updates to skills, rules, workflows, and backbone.yml. Do not write any change until I approve a diff.
+Use the daily-workflow-curator skill. Run node .vibekit/scripts/daily-enhance.mjs . --write-report and node .vibekit/scripts/validate-kit.mjs . Then propose updates to skills, rules, workflows, and backbone.yml. Do not write any change until I approve a diff.
 ```