minimal-vibe-coding-kit 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## Unreleased
+
+- 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.
+- Added safe updater: `mvck update` refreshes kit-owned files (skills, commands, rules, scripts, docs, agent mirrors), seeds user-owned files only when missing, refreshes managed blocks in place, backs up replaced files to `.vibekit/update-backup/<timestamp>/`, and supports `--dry-run`, `--json`, `--no-backup`, and `--profile`.
+- Stamped installed kit version in `.vibekit/KIT_VERSION` on install/update; `mvck doctor` now reports it with the update command.
+- Added update-behavior tests (stale-file refresh, new-skill backfill, user-file preservation, backup creation, non-kit target rejection).
+- Hardened installer managed-block fallback when template markers are missing.
+- 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 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.
+- Promoted `clearthought`, `sequential-thinking`, and `reviewing-4p-priorities` as native custom reasoning skills across shared, Claude, Codex, and Cursor surfaces.
+- Added first-time convention discovery so init proposals include repo-specific naming, architecture, resource, localization, and generated-definition rules before approval.
+- Added validation checks for mirrored skill-surface parity across shared, Claude, Cursor, and Codex paths.
+- Hardened autoresearch guidance so experiment loops honor first-time init, logged baselines, metric extraction, and AgentShield review for agent-surface changes.
+
+## 0.2.0
+
+- Added one-command installer CLI: `mvck install <project>`.
+- Added quick shell and PowerShell installers: `install.sh`, `install.ps1`.
+- Added compact `backbone.yml` template and automatic backbone detection helper.
+- Added clean first prompt and first-time init runbook.
+- Added Claude, Cursor, and Codex support surfaces.
+- Added shared skills for autoresearch coding, AgentShield security review, daily workflow curation, and kit init.
+- Added AgentShield read-only repo probe.
+- Added daily propose-only enhancement report.
+- Added validation script and GitHub Actions validation workflow.
+- Reduced root instruction boilerplate by moving details into docs and skills.

package/CLAUDE-template.md

@@ -0,0 +1,52 @@
+@AGENTS.md
+
+# Claude Code
+
+This file is intentionally small. Shared rules live in `AGENTS.md`, project facts live in `backbone.yml`, and long procedures live in `.claude/skills/`.
+
+## Startup
+
+1. Read `backbone.yml`.
+2. If `meta.template_status` is `uninitialized`, follow `FIRST_TIME_INIT.md` before other work.
+3. If initialized, follow `backbone.yml` `conventions` and continue with the user's task.
+
+## Useful skills
+
+- `/init-vibe` - initialize or repair the kit setup.
+- `/autoresearch-coding` - run a metric-driven improvement loop.
+- `/security-scan` - run AgentShield-style review.
+- `/daily-enhance` - propose rule, skill, and workflow improvements.
+
+## Hard rules
+
+- Show a diff and wait for explicit approval before changing root instruction files, `backbone.yml`, rules, skills, or workflows.
+- Do not deploy, rotate secrets, run migrations, delete data, or rewrite remote history without explicit approval.
+- Keep `.autoresearch/`, `results.tsv`, and `.vibekit/reports/` local unless the user asks to commit them.
+
+## English Learning & Grammar Correction
+
+### Grammar Correction Protocol
+
+When the user sends a message, **ALWAYS start by correcting their English grammar first** before providing the main response:
+
+1. **Quote their original message** in a blockquote
+2. **Provide the corrected version** with proper grammar
+3. **List the grammar fixes made** with brief explanations
+4. **Then proceed** with answering their request
+
+This helps the user learn English while getting assistance with their technical work.
+
+**Example Format:**
+
+```
+**Your original message:**
+> "now please using sequential thinking to helpme has instruction"
+
+**Corrected version:**
+> "Now please use sequential thinking to help me add an instruction"
+
+**Grammar fixes made:**
+- "using" → "use" (imperative form)
+- "helpme" → "help me" (two words)
+- "has instruction" → "add an instruction" (verb agreement)
+```

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,18 @@
+# Code of Conduct
+
+## Expected behavior
+
+- Be respectful and practical in technical discussion.
+- Focus critique on code, documentation, security risk, and user impact.
+- Assume good intent, but verify claims with reproducible evidence.
+- Avoid sharing secrets, private data, or exploit details in public threads.
+
+## Unacceptable behavior
+
+- Harassment, discrimination, threats, or personal attacks.
+- Publishing credentials, private keys, tokens, or sensitive logs.
+- Encouraging unsafe agent behavior such as hidden command execution or bypassing user approval.
+
+## Enforcement
+
+Maintainers may edit, hide, or remove comments and contributions that violate this code. Repeated or severe violations may result in a ban from project spaces.

package/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Thank you for improving Minimal Vibe Coding Kit. Keep changes small, reviewable, and safe for repos that already have their own agent instructions.
+
+## Development checks
+
+Run the full local check before opening a pull request:
+
+```bash
+npm test
+npm run security:probe
+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/`.
+- 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`.
+
+## Pull request checklist
+
+- Validation passes on Node 18, 20, and 22.
+- AgentShield probe passes or any warning is explained.
+- `npm run pack:dry-run` contains only intended release files.
+- Agent-surface changes are easy to audit.

package/FIRST_PROMPT.md

@@ -0,0 +1,54 @@
+# First prompts
+
+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.
+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.
+```
+
+## Claude
+
+```text
+Use /init-vibe. Keep CLAUDE.md short. Import shared AGENTS.md. Do not overwrite existing CLAUDE.md; append the managed block only.
+```
+
+## 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.
+```
+
+## 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.
+```
+
+## Autoresearch improvement loop for this kit
+
+```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 .
+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.
+Protected paths: .git .env* node_modules vendor secrets lockfiles.
+Budget: 3.
+```
+
+## AgentShield
+
+```text
+Use the agentshield-security-review skill. Run the read-only probe first. Then, if npm is available, run AgentShield scan. Report scanner-backed findings separately from manual judgment. Do not run hooks, MCP servers, or installer scripts just to inspect them.
+```
+
+## 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.
+```

package/FIRST_TIME_INIT.md

@@ -0,0 +1,165 @@
+# FIRST_TIME_INIT.md - bootstrap runbook
+
+Audience: Claude, Cursor, Codex, or any AI coding agent in a repo that just received Minimal Vibe Coding Kit.
+
+Keep this flow short. Detailed schema notes live in `.vbkit-docs/BACKBONE_REFERENCE.md`.
+
+## Requirements to print before starting
+
+Before writing anything, print this checklist and mark each item as found, missing, or inferred:
+
+1. `backbone.yml` exists.
+2. `AGENTS.md` exists or will be created/merged.
+3. `CLAUDE.md` exists or will be created from `CLAUDE-template.md` when Claude support is installed.
+4. At least one harness folder exists: `.claude/`, `.cursor/`, `.agents/`, or `.codex-plugin/`.
+5. Git status is known. If user changes exist, do not overwrite them.
+6. A validation command is inferred or set to `node .vbkit-scripts/validate-kit.mjs .` for the kit itself.
+7. Protected paths include `.env*`, secrets, lockfiles, generated files, build output, migrations, and infra unless the user says otherwise.
+8. Existing naming, architecture, resource, and localization conventions are scanned or marked missing.
+
+## Canonical prompt
+
+```text
+Read 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.
+```
+
+## Done check
+
+Open `backbone.yml`.
+
+- If `meta.template_status` is `initialized`, skip init. If `.vibekit/INIT_DONE` is missing, recreate it as a local cache and continue.
+- If `meta.template_status` is `uninitialized`, continue.
+- If `backbone.yml` is missing, stop and tell the user to install/copy the kit first.
+
+The sentinel file is not required in source control. `backbone.yml` is the durable source of truth.
+
+## Detect
+
+Prefer filesystem evidence over README claims.
+
+- Project name: `package.json:name`, `pyproject.toml` project name, `go.mod` module basename, else folder name.
+- Type: monorepo marker (`pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, `go.work`) means monorepo; otherwise single-repo unless multiple app roots are obvious.
+- Primary language: strongest marker or source file counts.
+- Package manager: lockfile wins.
+- Commands: infer test, lint, typecheck, build from package scripts, Makefile, Go, Python, Rust, Java, dotnet, PHP, Ruby, or existing CI.
+- Paths: infer source, tests, docs, config, generated output.
+- Conventions: infer naming style, folder architecture, shared resource access, localization/message access, generated-code boundaries, and per-app or per-package differences.
+- Project mode: `greenfield` when no source code exists yet, otherwise `brownfield`. Stored as `project.mode`.
+- PRD/docs: detect an existing PRD, requirements, or spec document. Stored as `project.prd` (path or `none`).
+
+## Project understanding (PRD)
+
+Always offer a short interview during init so the kit understands what the project is and where to focus, then propose a PRD. Do this whether the repo is empty, has code, or already has docs.
+
+Ask (keep it short):
+
+1. What is this project and who is it for?
+2. What core problem does it solve, and what is the primary goal/focus right now?
+3. What does success look like (key outcomes or metrics)?
+4. What are the key constraints or non-goals?
+5. Brownfield only: which existing area should we improve first?
+
+Then:
+
+- If `project.prd` is `none`, propose creating `.vbkit-docs/PRD.md` from `.vbkit-docs/templates/PRD_TEMPLATE.md` using the answers, and set `project.prd` to that path in the same diff.
+- If a PRD already exists, read it, link it in `project.prd`, and offer to refresh it without overwriting unapproved content.
+- Record domain terms and acronyms in `.vbkit-docs/CONTEXT.md` (scaffold from `.vbkit-docs/templates/CONTEXT_TEMPLATE.md`) and link it in `project.context`, so future agents stay concise.
+- Keep the PRD short: it captures intent and focus, not a full specification.
+
+## FIRST_TIME_INIT_RULES
+
+Create project rules from evidence in the existing repo, not from a fixed language or framework template.
+
+- Scope rules to the smallest accurate boundary: repo, app, package, service, module, or folder. In monorepos and multi-repo workspaces, do not force one package's style onto another when evidence differs.
+- Naming: detect dominant file, directory, symbol, test, component, handler, model, and module naming patterns from nearby code. If no pattern is clear, propose a neutral default and ask before writing it into `backbone.yml`.
+- Architecture: detect existing structures such as MVC, MVVM, feature modules, services/repositories, domain/application/infrastructure layers, route/page/screen folders, package boundaries, or framework-specific layouts. New code should enter the nearest matching structure before introducing a new top-level pattern.
+- Resources: detect whether assets, images, icons, routes, API paths, themes, configs, or other shared resources are accessed through constants, registries, generated APIs, or helper modules. If such a pattern exists, rules must prefer that accessor over hardcoded literals. For example, prefer a detected `AppImages.logo` or equivalent project accessor over a raw path such as `assets/images/logo.png`.
+- Localization and copy: detect catalogs and accessors such as `.arb`, locale folders, message files, generated localization APIs, or translation helpers. If present, rules must prefer those accessors over hardcoded user-facing text.
+- Generated and shared definitions: detect generated files, enums, schemas, OpenAPI/GraphQL clients, design tokens, route maps, or other single-source definitions. Rules should reuse or update the source definition instead of duplicating literals.
+- Missing conventions: if the repo lacks a shared abstraction and adding one would affect many files, propose it as a pending rule and ask the user to reply `yes`, `edit`, or `abort` before implementation.
+- Store confirmed rules in `backbone.yml` under `conventions`. Future agents must follow those confirmed rules and ask before changing them.
+
+Optional helper:
+
+```bash
+node .vbkit-scripts/init-backbone.mjs . --propose
+```
+
+## Propose before writing
+
+Show one unified diff for:
+
+- `backbone.yml`
+- the `backbone.yml` `conventions` rules inferred from existing code, including evidence and unresolved questions
+- `CLAUDE.md` managed block or new file when Claude is active
+- `AGENTS.md` managed block or new file when Codex/general agent support is active
+- missing `.cursor/rules` or `.agents/skills` shims only if the installer did not add them
+
+Ask exactly:
+
+```text
+Apply this proposed backbone and convention rules? Reply yes, edit, or abort.
+```
+
+## Apply after user says yes
+
+1. Write approved changes only.
+2. Set `meta.template_status: initialized`.
+3. Set `meta.initialized_at` to current UTC ISO timestamp.
+4. Create `.vibekit/INIT_DONE` with the same timestamp.
+5. Run the validation command from `backbone.yml`.
+6. Print a short completion summary.
+7. Offer graduation: once the user confirms setup is done, run the cleanup in the Graduation section below to remove one-time bootstrap files.
+
+CLI helper after approval:
+
+```bash
+node .vbkit-scripts/init-backbone.mjs . --write --yes
+```
+
+## Merge rules
+
+### CLAUDE.md
+
+- If no `CLAUDE.md` exists, copy `CLAUDE-template.md` to `CLAUDE.md`.
+- If `CLAUDE.md` exists, append or replace only this managed block:
+
+```markdown
+<!-- BEGIN: minimal-vibe-coding-kit -->
+@AGENTS.md
+
+## Minimal Vibe Coding Kit
+
+- Read `backbone.yml` before changing code.
+- If `meta.template_status` is `uninitialized`, follow `FIRST_TIME_INIT.md` and wait for approval before writing.
+- After init, follow `backbone.yml` `conventions` before adding new project patterns.
+- Prefer project skills for multi-step workflows: `/autoresearch-coding`, `/security-scan`, `/daily-enhance`.
+<!-- END: minimal-vibe-coding-kit -->
+```
+
+### AGENTS.md
+
+- If no `AGENTS.md` exists, create it from this kit.
+- If it exists, append or replace only the Minimal Vibe managed block.
+- Keep project-specific content outside the managed block.
+
+## Graduation (cleanup after setup)
+
+Once init is `initialized` and the first prompt is complete, the bootstrap files are no longer needed in the project. Offer to graduate them so the repo stays clean.
+
+- Preview: `node .vbkit-scripts/vibekit-finalize.mjs . --propose`
+- Apply after the user agrees: `node .vbkit-scripts/vibekit-finalize.mjs . --write --yes`
+
+This moves one-time files (`FIRST_TIME_INIT.md`, `FIRST_PROMPT.md`, `PUSH_TO_GITHUB.md`, `CLAUDE-template.md` once `CLAUDE.md` exists) into the folder named by `automation.finalize.cleanup_dir` (default `_vibekit-cleanup/`), writes a `RESTORE.md`, and sets `automation.finalize.marker`. It is idempotent, reversible with `--restore --write`, and refuses to run on the kit source repo. The durable project map is `backbone.yml`; none of the graduated files are needed to keep working. Delete the cleanup folder when satisfied.
+
+## Guardrails
+
+- No silent writes to root instructions, rules, skills, workflows, or `backbone.yml`.
+- Do not run package scripts, hooks, MCP servers, deploys, migrations, or destructive commands during init.
+- Do not modify protected paths unless the user explicitly approves.
+- Keep `CLAUDE.md`, `AGENTS.md`, and Cursor rules concise. Move procedures into skills.
+- Do not hardcode paths, resources, user-facing text, config keys, routes, or generated values when the repo already has a shared accessor or definition.
+- If unsure, produce a proposal and ask for `yes`, `edit`, or `abort`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Minimal Vibe Coding Kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.