minimal-vibe-coding-kit 0.3.0

package/.vbkit-docs/BACKBONE_REFERENCE.md

@@ -0,0 +1,59 @@
+# Backbone reference
+
+`backbone.yml` is the project map. Keep it short enough that agents can read it every session.
+
+## Required sections
+
+- `meta`: init status and schema version.
+- `project`: name, description, repo type, primary language, package manager, `mode` (greenfield/brownfield), `prd` (path or `none`), `context` (glossary path or `none`).
+- `paths`: code, tests, docs, and generated output.
+- `conventions`: user-reviewed project rules inferred from existing code.
+- `commands`: install, test, lint, typecheck, build, validate.
+- `policy`: branch, commit, editable paths, protected paths.
+- `agent_surfaces`: Claude, Cursor, Codex, shared skills, shared commands.
+- `automation`: autoresearch, daily enhance, finalize (graduation cleanup), security.
+
+## Init status
+
+`meta.template_status` is the durable init flag.
+
+- `uninitialized`: agent must run `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.
+
+## Command selection
+
+Use the most specific command the repo already supports.
+
+Examples:
+
+- Node: `pnpm test`, `npm test`, `npm run build`.
+- Python: `pytest -q`, `ruff check .`, `pyright`.
+- Go: `go test ./...`, `go build ./...`.
+- Rust: `cargo test`, `cargo clippy --all-targets`.
+- Java: `mvn test`, `gradle test`.
+
+If no command is known, leave `validate` as a safe echo and ask the user to fill it.
+
+## Conventions
+
+The `conventions` section is created during first-time init and must be reviewed before writing. It should capture repo-specific rules with evidence, not a fixed framework template.
+
+Include:
+
+- Naming style for files, directories, and symbols.
+- Architecture or folder patterns, scoped per app/package when evidence differs.
+- Resource access rules for assets, images, routes, API paths, config keys, design tokens, or generated definitions.
+- Localization/message access rules when catalogs or generated accessors exist.
+- Custom team rules confirmed by the user.
+
+If the repo has an accessor such as `AppImages.logo`, an asset registry, generated routes, `.arb` localization, or a message helper, future work should use that pattern instead of hardcoded literals. If no convention exists and adding one would affect many files, ask before adding the abstraction.
+
+## Protected paths
+
+Protect secrets, generated output, dependency folders, lockfiles, migrations, and infra by default. The user can explicitly approve a narrow exception.
+
+## Editable paths
+
+For normal tasks, editable paths should be narrow. For an initial kit install, `.` is acceptable only until project-specific paths are detected.

package/.vbkit-docs/INSTALL.md

@@ -0,0 +1,120 @@
+# Install guide
+
+## Local install
+
+```bash
+./install.sh /path/to/project
+```
+
+## Node install
+
+```bash
+node .vbkit-scripts/mvck.mjs install /path/to/project --profile all
+```
+
+Profiles:
+
+- `claude`: `CLAUDE.md`, `.claude/`, Claude skills, agents, commands, rules.
+- `cursor`: `.cursor/rules`, `.cursor/commands`, Cursor skill entrypoints.
+- `codex`: `AGENTS.md`, `.agents/skills`, `.codex-plugin`, `.codex` examples.
+- `all`: every profile.
+
+## Safe behavior
+
+The installer:
+
+- skips existing files unless `--force` is passed;
+- appends managed blocks instead of replacing existing `CLAUDE.md`, `AGENTS.md`, and `.gitignore`;
+- does not mark `backbone.yml` initialized;
+- does not run package scripts in the target project.
+
+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
+```
+
+## Update an existing project
+
+When a newer kit version ships, refresh kit-owned files without touching user-owned ones:
+
+```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
+```
+
+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;
+- 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`;
+- records the kit version in `.vibekit/KIT_VERSION` (shown by `mvck doctor`).
+
+Preview without writing:
+
+```bash
+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.
+
+## After install
+
+Paste the universal prompt from `FIRST_PROMPT.md`, or run:
+
+```bash
+node .vbkit-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
+```
+
+Review the proposal. After approval:
+
+```bash
+node .vbkit-scripts/init-backbone.mjs . --write --yes
+```
+
+## Doctor
+
+Run a read-only health check after install:
+
+```bash
+node .vbkit-scripts/mvck.mjs doctor .
+```
+
+Generate a handoff report:
+
+```bash
+node .vbkit-scripts/mvck.mjs doctor . --write-report
+```
+
+## Native reasoning skills
+
+The installer includes three flexible custom reasoning skills across Claude, Codex, and Cursor. These install as full skill folders, including examples and references for progressive disclosure:
+
+- `clearthought`: clarify ambiguous tasks and choose a reasoning mode.
+- `sequential-thinking`: split complex work into ordered implementation steps.
+- `reviewing-4p-priorities`: classify review findings or bugs as P0-P4 and choose fix order.
+
+## Visual design loop skill
+
+The installer also includes `visual-design-loop` for Claude and Codex surfaces. Use it when a loop goal touches UI polish, screenshots, rendering, visual QA, or visible frontend behavior.
+
+## User-invoked utility skills
+
+Two user-invoked skills install across Claude, Codex, and Cursor surfaces:
+
+- `memento`: write a `MEMENTO.md` working note before closing a multi-day task (`/memento`), then resume from it in the next session (`/memento resume`).
+- `coding-level`: set the explanation register from 0 (ELI5) to 5 (expert peer) with `/coding-level N`; stays active until reinvoked.

package/.vbkit-docs/RESEARCH_NOTES.md

@@ -0,0 +1,22 @@
+# Research notes used for this enhancement
+
+The kit follows these design decisions:
+
+1. Keep always-loaded instruction files short.
+2. Move procedures into skills because skills load only when used.
+3. Provide tool-specific discovery paths instead of assuming one tool reads every folder.
+4. Use a canonical shared skill body plus thin harness shims to reduce drift.
+5. Run security review on agent surfaces, not only application source code.
+6. Make daily improvement propose-only by default.
+7. Use deterministic validation as the autoresearch metric for the kit itself.
+
+## Autoresearch metric for this repo
+
+```text
+Goal: improve Minimal Vibe Coding Kit quality.
+Metric command: node .vbkit-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.
+Budget: 3.
+```

package/.vbkit-docs/SECURITY_MODEL.md

@@ -0,0 +1,40 @@
+# Security model
+
+## Agent surfaces
+
+Review these before merging changes:
+
+- `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`
+- `.claude/**`, `.cursor/**`, `.agents/**`, `.codex-plugin/**`
+- `skills/**`, `.vbkit-commands/**`, `.vbkit-scripts/**`, `hooks/**`
+- `.mcp.json`, `mcp.json`, `mcp-configs/**`
+- installer scripts and CI workflows
+
+## AgentShield workflow
+
+Read-only probe:
+
+```bash
+node .vbkit-scripts/agentshield-probe.mjs .
+```
+
+Full scanner when available:
+
+```bash
+npx ecc-agentshield scan --path . --format text --min-severity medium
+```
+
+## Findings labels
+
+- `scanner-backed`: comes from AgentShield or deterministic probe output.
+- `manual-confirmed`: verified by reading active repo files.
+- `manual-suspected`: plausible risk that needs maintainer confirmation.
+
+## Do not do these silently
+
+- Run untrusted hooks or MCP servers.
+- Execute install scripts from remote sources.
+- Deploy or run migrations.
+- Rotate or print secrets.
+- Relax tool permissions.
+- Enable wildcard shell execution.

package/.vbkit-docs/TOOLING_GUIDE.md

@@ -0,0 +1,22 @@
+# Tooling guide
+
+## 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/`.
+
+## Cursor
+
+Use `.cursor/rules/*.mdc`. The kit creates always-on core rules plus scoped rules for init, autoresearch, and security. Keep Cursor rules short; link to skills and docs for long procedures.
+
+## Codex
+
+Use `AGENTS.md` for repo instructions and `.agents/skills/*/SKILL.md` for skills. The kit also includes `.codex-plugin/plugin.json` so the shared skills can be packaged as a plugin.
+
+## Shared skill strategy
+
+Canonical skill bodies live in `skills/<skill-name>/`. Harness-specific folders contain small shims:
+
+- `.claude/skills/<skill-name>/SKILL.md`
+- `.agents/skills/<skill-name>/SKILL.md`
+
+This reduces drift while still giving each tool the path it expects.

package/.vbkit-docs/backbone.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/giang6283623/minimal-vibe-coding-kit/backbone.schema.json",
+  "title": "Minimal Vibe Coding Kit backbone.yml",
+  "type": "object",
+  "required": [
+    "version",
+    "meta",
+    "project",
+    "conventions",
+    "commands",
+    "policy",
+    "agent_surfaces",
+    "automation"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "meta": {
+      "type": "object",
+      "required": ["template_status", "schema_version"],
+      "properties": {
+        "template_status": {
+          "type": "string",
+          "enum": ["uninitialized", "initialized"]
+        },
+        "schema_version": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "project": {
+      "type": "object",
+      "required": ["name", "primary_language", "mode"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "primary_language": { "type": "string", "minLength": 1 },
+        "mode": { "type": "string", "enum": ["greenfield", "brownfield"] },
+        "prd": { "type": "string" },
+        "context": { "type": "string" }
+      }
+    },
+    "conventions": {
+      "type": "object",
+      "required": ["review_required_before_write"],
+      "properties": {
+        "review_required_before_write": { "type": "boolean" },
+        "scope": { "type": "string" },
+        "naming": { "type": "object" },
+        "architecture": { "type": "object" },
+        "resources": { "type": "object" },
+        "localization": { "type": "object" },
+        "custom_rules": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "commands": {
+      "type": "object",
+      "required": ["validate"],
+      "properties": {
+        "validate": { "type": ["string", "null"] }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "required": ["protected_paths"],
+      "properties": {
+        "protected_paths": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        }
+      }
+    },
+    "agent_surfaces": {
+      "type": "object",
+      "minProperties": 1
+    },
+    "automation": {
+      "type": "object",
+      "required": ["finalize", "security"],
+      "properties": {
+        "finalize": {
+          "type": "object",
+          "required": ["cleanup_dir"],
+          "properties": {
+            "cleanup_dir": { "type": "string", "minLength": 1 },
+            "marker": { "type": "string" },
+            "one_time_files": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        },
+        "security": {
+          "type": "object",
+          "required": ["probe"],
+          "properties": {
+            "probe": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    }
+  }
+}

package/.vbkit-docs/templates/CONTEXT_TEMPLATE.md

@@ -0,0 +1,47 @@
+# Project context
+
+> Scaffolded by Minimal Vibe Coding Kit. A short, shared glossary and map so any
+> agent (Claude, Cursor, Codex) navigates this project with less back-and-forth.
+> Keep it current and terse — definitions, not prose.
+
+## Domain glossary
+
+Terms, acronyms, and entities specific to this project. One line each.
+
+- **<Term>** — <plain-language meaning, and where it lives in code if relevant>.
+- **<Acronym>** — <expansion + what it refers to here>.
+
+## Key areas
+
+Where the important things live, so agents jump straight to them.
+
+- Entry point(s):
+- Core domain logic:
+- Configuration:
+- Tests:
+- Build/deploy:
+
+## Conventions in use
+
+Pointers to the patterns this repo already follows (also captured in `backbone.yml` `conventions`).
+
+- Naming:
+- Architecture / folder layout:
+- Shared resources (assets, routes, config, generated code) — accessor to use:
+- User-facing copy / localization — accessor to use:
+
+## External systems & integrations
+
+- Services, APIs, queues, or third parties this project talks to:
+- Credentials/secrets location (names only, never values):
+
+## Gotchas
+
+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,
+protected paths). Link `project.context` in `backbone.yml` to this file.

package/.vbkit-docs/templates/PRD_TEMPLATE.md

@@ -0,0 +1,48 @@
+# <Project name> — Product Requirements
+
+> Scaffolded by Minimal Vibe Coding Kit during init. Keep it short and current;
+> agents read this to understand intent. Fill answers from the init interview.
+
+## 1. Summary
+
+One or two sentences: what this project is and who it is for.
+
+## 2. Problem & goal
+
+- Problem it solves:
+- Primary goal / focus right now:
+- Why now / motivation:
+
+## 3. Users & use cases
+
+- Primary users:
+- Top use cases (1–3):
+
+## 4. Success criteria
+
+- What good looks like (outcomes or metrics):
+- How we will know we shipped the right thing:
+
+## 5. Scope
+
+- In scope (this iteration):
+- Out of scope / non-goals:
+
+## 6. Constraints & assumptions
+
+- Technical / platform constraints:
+- Deadlines, budget, compliance, or other constraints:
+- Assumptions to validate:
+
+## 7. Focus area (brownfield)
+
+If existing code: which module, surface, or flow are we improving first, and why.
+
+## 8. Open questions
+
+- Things still undecided that need an answer before building.
+
+---
+
+Linked context: see `.vbkit-docs/CONTEXT.md` for domain terminology and `backbone.yml`
+for the project map (`project.mode`, `project.prd`, conventions, commands).

package/.vbkit-scripts/agentshield-probe.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const target = path.resolve(process.argv[2] || process.cwd());
+const extra = process.argv.slice(3);
+const probe = path.join(target, 'skills/agentshield-security-review/scripts/agentshield_repo_probe.py');
+
+if (!fs.existsSync(probe)) {
+  console.error(`AgentShield probe not found: ${path.relative(target, probe)}`);
+  process.exit(1);
+}
+
+for (const python of ['python', 'python3', 'py']) {
+  const result = spawnSync(python, [probe, target, ...extra], { stdio: 'inherit' });
+  if (result.error?.code === 'ENOENT') continue;
+  process.exit(result.status ?? 1);
+}
+
+console.error('No Python executable found. Install Python 3 or run the probe manually.');
+process.exit(1);

package/.vbkit-scripts/daily-enhance.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const target = path.resolve(args.find((a) => !a.startsWith('--')) || process.cwd());
+const writeReport = args.includes('--write-report');
+const now = new Date();
+
+function exists(rel) { return fs.existsSync(path.join(target, rel)); }
+function list(dir) {
+  const p = path.join(target, dir);
+  if (!fs.existsSync(p)) return [];
+  const out = [];
+  function walk(current) {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const child = path.join(current, entry.name);
+      if (entry.isDirectory()) walk(child);
+      else out.push(path.relative(target, child).replaceAll(path.sep, '/'));
+    }
+  }
+  walk(p);
+  return out;
+}
+
+const checks = [];
+for (const rel of ['backbone.yml', 'AGENTS.md', 'FIRST_TIME_INIT.md', 'skills/autoresearch-coding/SKILL.md', 'skills/agentshield-security-review/SKILL.md']) {
+  checks.push(`- ${rel}: ${exists(rel) ? 'found' : 'missing'}`);
+}
+
+const skills = list('skills').filter((f) => f.endsWith('SKILL.md'));
+const claudeSkills = list('.claude/skills').filter((f) => f.endsWith('SKILL.md'));
+const codexSkills = list('.agents/skills').filter((f) => f.endsWith('SKILL.md'));
+const cursorRules = list('.cursor/rules').filter((f) => f.endsWith('.mdc'));
+
+let validation = 'not run';
+const validator = path.join(target, '.vbkit-scripts/validate-kit.mjs');
+if (fs.existsSync(validator)) {
+  const result = spawnSync(process.execPath, [validator, target], { encoding: 'utf8' });
+  validation = result.stdout.trim() || result.stderr.trim() || `exit ${result.status}`;
+}
+
+const suggestions = [];
+if (!exists('.claude/skills/agentshield-security-review/SKILL.md')) suggestions.push('Add Claude AgentShield skill shim.');
+if (!exists('.agents/skills/agentshield-security-review/SKILL.md')) suggestions.push('Add Codex AgentShield skill shim.');
+if (!exists('.cursor/rules/020-security-agentshield.mdc')) suggestions.push('Add Cursor AgentShield security rule.');
+if (skills.length > 12) suggestions.push('Review skill descriptions for progressive disclosure; keep trigger text concise.');
+if (!exists('.github/workflows/vibekit-validate.yml')) suggestions.push('Add CI validation for agent surfaces.');
+if (!suggestions.length) suggestions.push('No structural gaps found. Review docs for stale project-specific examples and run AgentShield full scan when npm is available.');
+
+const report = `# Daily Minimal Vibe Coding Kit report\n\nGenerated: ${now.toISOString()}\n\n## Required files\n\n${checks.join('\n')}\n\n## Surface counts\n\n- Shared skills: ${skills.length}\n- Claude skill shims: ${claudeSkills.length}\n- Codex skill shims: ${codexSkills.length}\n- Cursor rules: ${cursorRules.length}\n\n## Validation output\n\n\`\`\`text\n${validation}\n\`\`\`\n\n## Suggested next improvements\n\n${suggestions.map((s) => `- ${s}`).join('\n')}\n\n## Write policy\n\nThis report is propose-only. An agent may turn suggestions into a diff, but must wait for explicit user approval before writing.\n`;
+
+console.log(report);
+
+if (writeReport) {
+  const dir = path.join(target, '.vibekit', 'reports');
+  fs.mkdirSync(dir, { recursive: true });
+  const name = `daily-${now.toISOString().slice(0, 10)}.md`;
+  fs.writeFileSync(path.join(dir, name), report);
+  console.log(`\nWrote ${path.relative(target, path.join(dir, name))}`);
+}