just-vibe 0.7.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "just-vibe",
+  "interface": { "displayName": "just-vibe" },
+  "plugins": [
+    {
+      "name": "just-vibe",
+      "source": { "source": "local", "path": "./plugins/just-vibe" },
+      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
+      "category": "Productivity"
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "just-vibe",
+  "metadata": { "description": "Tools, skills, and commands for coding agents." },
+  "owner": { "name": "Zachary Martin" },
+  "plugins": [
+    {
+      "name": "just-vibe",
+      "source": "./plugins/just-vibe",
+      "description": "Tools, skills, and commands for coding agents."
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## 0.7.0
+
+- Extend remember to merge explicit rules or current conversation decisions into CLAUDE.md/AGENTS.md, with shared instructions for both hosts, preview mode and optional named checkpoints in one invocation. Preserve existing guidance, user corrections and scope; distinguish saved files from verified host loading.
+- Route instruction-memory requests to remember without confusing application caches or ML memory usage with project instructions.
+
+- Let auto complete small local tasks without formal stage calls, escalating to tracked execution when dependencies, recovery or effects require it.
+- Show a small starter catalog by default; keep the complete catalog under tools --all. Rank routes using task intent, detected JS/Python frameworks and prerequisite status, with reasons and ambiguity instead of implied certainty.
+- Add conditionally loaded authentication, dialog, combobox, date input, ML training and delivery guides to existing workflows.
+- Add explicit project preferences, revision-checked notes and named checkpoints with repository/content/index staleness checks. Stored context cannot override current instructions or restore authorization.
+- Add bounded GitHub, Vercel, Playwright and SQL migration evidence collectors with target identity, actual results and limitations.
+- Add optional project hooks for configured checks, single-file formatting and continuation summaries. Exact configuration requires separate local trust; changed configuration invalidates it. Hooks preserve staged files, limit execution, deduplicate unchanged work and never force a new turn.
+
+## 0.6.0
+
+- Replace repeated guidance in 27 command contracts with concrete ownership, timing, failure, recovery and verification decisions across backend, ML, Git/GitHub, React, frontend delivery, architecture, decisions and LLM systems.
+- Require contract-backed expectations and artifact-specific evidence in shared execution guidance. Add worked methods for cache cancellation/generations, transaction ownership, versioned historical features and preserving partially staged commits.
+- Add a repeated four-arm repository benchmark with independent behavior assertions, scorer controls, immutable trial inputs, profile ablation and retained failures. Record 32 original and eight development trials, with token/timing data as supporting observations. Distinguish narrow correctness from overall output quality and convenience; add a contextual review guide for judgment, clarity, discovery and correction burden.
+- Preserve original scores when correcting test-report interpretation; compare every arm under the same corrected scorer. Benchmark model calls remain explicitly opt-in and are excluded from normal validation.
+
+## 0.5.0
+
+- Add 112 task-scoped engineering profiles with distinct priorities, decision rules, verification, boundaries and candidate workflows. Include senior, staff, principal and architecture specialties.
+- Add profile discovery and selection skills plus CLI profile utilities. User choices are pinned by default; agent choices cannot override user pins. Role changes preserve task scope, permissions, budgets and history.
+- Require user ownership and no agent self-attribution in commits, PRs, comments, release notes or other messages. Preserve human attribution and required third-party notices.
+- Package every profile with the plugin and test discovery, pinning, clearing, state preservation and archive execution. Profile instructions are guidance, not a claim of evaluation for every profession or model.
+
+## 0.4.0
+
+- Expand all 210 canonical command contracts with selection boundaries, concrete decision branches, outputs and normal/edge/missing-evidence examples; add applied methods to all 22 pack guides.
+- Make do, responsive and a11y inherit canonical behavior; reject alias overrides and deduplicate routing recommendations.
+- Add checked action amendments and evidence-backed supersession of blocked/failed stages while preserving history, original criteria and budgets. Require reconciliation of uncertain external effects.
+- Separate structural, utility and behavioral validation labels. Add 21 isolated independent behavioral fixtures, executable code/mutation assertions and baseline/matched-ECC comparison preparation.
+- Preserve native quiz availability limitations and distinguish supplied-instruction agent trials from native plugin and live-provider validation.
+
+## 0.3.0
+
+- Install the plugin files bundled in the package into a persistent local marketplace. Default installation no longer fetches the private GitHub repository or depends on a temporary package-manager cache.
+- Add explicit `--github` for the previous GitHub installation channel; retain `--local` for persistent development checkouts. Existing GitHub users must pass `--github` or deliberately migrate their marketplace.
+- Preserve managed copies on repeated setup and host failures; replace them on explicit update. Refuse unmanaged destinations, symlinks and conflicting marketplace sources.
+- Add the MIT license, package-content and release-metadata checks, clean npm/pnpm/Yarn execution tests, and a guarded trusted-publishing workflow.
+- Add Windows CI coverage and support resolving executable extensions and standard npm Node command shims without evaluating shell arguments.
+- Keep the 213 skills and documented v0.2 behavioral limitations. This release changes delivery, not the underlying model capabilities.
+
+## 0.2.0
+
+- Add 212 workflow names plus setup, catalog discovery, bounded run records, teaching and native quiz adapters.
+- Validate native Codex/Claude installation lifecycles and record representative agent trials and remaining limitations.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zachary Martin
+
+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.

package/README.md

@@ -0,0 +1,282 @@
+# just-vibe
+
+Tools, skills, and commands for coding agents.
+
+**v0.7 ships 112 engineering profiles and 215 skill names backed by 212 canonical workflows** for Codex and Claude Code: focused skills for development, architecture, decisions, Git/GitHub, Vercel, Vite, React, UI, backend, APIs, databases, data, ML, LLMs, testing, security, and operations. Each canonical workflow has selection guidance, scope, concrete decision branches, evidence requirements, outputs, verification, recovery conditions and three example requests. Applied methods live in 22 pack guides.
+
+The active coding agent executes the workflows with its available tools. The dependency-free Node.js utilities provide catalog search, project inspection, capability discovery, and bounded run-state validation. Installing just-vibe does not connect services, grant permissions, provision compute, or make every workflow's prerequisites available.
+
+v0.7 adds a quick path for simple work, a small starter catalog, contextual routing with reasons, project preferences and checkpoints, explicit evidence collectors, and optional project hooks. Detailed auth, component, training and delivery scenarios load only when relevant. See [daily workflows](plugins/just-vibe/references/daily-workflows.md) for configuration and examples, and the [v0.7 validation record](evals/releases/0.7.0.md) for tested scope and limits.
+
+## Use the workflows
+
+In Claude Code, use a command followed by as much context as needed:
+
+```text
+/just-vibe:auto fix checkout, add regression coverage, and verify.
+Keep the existing API. No new dependencies. Do not push.
+
+/just-vibe:tools react
+/just-vibe:tools --available
+/just-vibe:help my model works offline but fails in production
+/just-vibe:teach linked lists, with a worked insertion example
+/just-vibe:teach the concepts I need to implement ml-split
+/just-vibe:teach-test linked lists; five questions, one at a time
+/just-vibe:git-split separate formatting from the checkout fix; show the grouping first
+/just-vibe:vercel-build-fix compare this preview's logs with the local build
+/just-vibe:ml-leakage prediction happens 30 days before cancellation; inspect only
+```
+
+In Codex, select the corresponding skill from the **just-vibe** plugin in the skill picker and append the same brief. `do` aliases `auto`, `responsive` aliases `ui-responsive`, and `a11y` aliases `ui-accessibility`; each inherits one canonical implementation. `tools` browses availability; `help` explains which workflow fits a scenario. Inspect, plan, and apply modes preserve the user's constraints and existing authorization. Read the [full command reference](plugins/just-vibe/references/command-reference.md).
+
+`teach` explains a standalone topic or the prerequisites behind a particular workflow. It adapts to your experience, uses worked examples, connects concepts to actual implementation where available, and offers optional practice. Teaching a tool does not execute it.
+
+`teach-test` uses the host's **native multiple-choice question dialog**, waits for your answer, explains mistakes, and adapts the next question. Request test mode to defer feedback until the end. It requires a question tool available and permitted in the current host/mode; when unavailable, it reports that limitation instead of printing inline quiz questions. [Interactive teaching behavior](plugins/just-vibe/references/teach-test.md) documents the adapters and quiz state.
+
+Release testing verified a real native quiz in Claude Code. The tested Codex CLI session restricted question tools to clarification/planning uses, so it correctly stopped without a quiz. Codex quiz adapters are included, but interactive assessment is not available in that tested mode. See the [v0.2 validation record](evals/releases/0.2.0.md) for the tested workflows and remaining environment limitations.
+
+Shared host packaging and context behavior follow the [OpenAI skill format](https://developers.openai.com/plugins/build/skills) and [Claude Code skill argument handling](https://code.claude.com/docs/en/skills#pass-arguments-to-skills). No dynamic shell interpolation is used in skill files.
+
+## Remember project instructions
+
+Save decisions and corrections from the current conversation in one invocation:
+
+```text
+/just-vibe:remember context
+/just-vibe:remember context both
+/just-vibe:remember context both, including a checkpoint named checkout for unfinished work
+```
+
+In Codex, select **remember** from just-vibe and append the same brief. The skill updates the established `CLAUDE.md` or `AGENTS.md`, merges existing guidance and saves only explicit instructions and accepted decisions. `both` keeps common rules in `AGENTS.md` with a relative import in `CLAUDE.md`. A checkpoint keeps temporary progress separate. You can also append one specific rule or ask for a preview without writing.
+
+This is an agent workflow using the host's file tools; terminal `project remember` only stores JSON notes. Saved instructions improve continuity but do not guarantee adherence or recover unavailable chat history. See [merging, host loading and examples](plugins/just-vibe/references/instruction-memory.md). Update older installations to receive this extension.
+
+## Engineering profiles
+
+Profiles shape the agent's priorities and verification throughout a task. They are separate from commands: a machine learning engineer emphasizes prediction-time data, evaluation and serving parity; a frontend engineer emphasizes state, interactions and rendered behavior. Each of the **112 profiles** has concrete priorities, a decision rule, checks, a scope boundary and candidate workflows.
+
+```text
+/just-vibe:profiles architecture
+/just-vibe:profile machine-learning-engineer with mlops-engineer as secondary
+/just-vibe:profile frontend-engineer for this task
+/just-vibe:profile principal-engineer; review the design without expanding the project
+/just-vibe:profile auto — choose an appropriate role for this task
+/just-vibe:profile status
+/just-vibe:profile clear
+```
+
+In Codex, select the **profile** or **profiles** skill in the plugin picker and append the same request. Explicit choices are pinned for the current task. The agent may choose an unpinned role from task evidence, but cannot replace a user pin. Choose one primary role and up to two complementary roles. Profiles preserve the original brief, scope, mode, permissions and budgets; they do not create additional agents or persist global preferences.
+
+The catalog covers application engineering, interface and experience, platform/infrastructure, data/databases, ML/AI, security/privacy, quality/technical leadership, and systems/specialized computing. Examples include firmware, robotics, compilers, graphics, game networking, geospatial computing, scientific software, privacy, identity, AI evaluation, agent systems, inference, and data governance.
+
+Architecture and seniority profiles have different emphasis:
+
+| Profile | Focus |
+|---|---|
+| Senior software engineer | Complete a bounded implementation with maintainable choices |
+| Staff engineer | Cross-team interfaces, migration and adoption |
+| Principal engineer | Systemic constraints, technical direction and reversible strategy |
+| Software architect | System responsibilities, boundaries and contracts |
+| Solutions architect | Fit a specific use case to a workable system |
+| Enterprise architect | Shared capabilities and transitions across systems |
+| Domain architects | Frontend, data, cloud, security, ML, platform and integration architecture |
+
+Titles vary across companies; these are working approaches, not credentials or grants of authority. Browse the [complete profile catalog](plugins/just-vibe/references/profile-reference.md) and [selection/runtime guide](plugins/just-vibe/references/profiles.md).
+
+The [v0.5 profile validation record](evals/releases/0.5.0.md) distinguishes tested profile selection and packaging from profession-specific model judgment.
+
+All changes are owned by the user. Commit messages, PRs, comments and other messages must contain **no agent self-attribution**, agent co-author trailers, generated-by signatures or AI badges. Existing human attribution and required third-party notices are preserved. See the [ownership rule](plugins/just-vibe/references/execution.md#ownership-and-attribution).
+
+## Terminal utilities
+
+From this checkout:
+
+```sh
+node bin/just-vibe.mjs tools
+node bin/just-vibe.mjs tools --pack ml-evaluation --json
+node bin/just-vibe.mjs tools --available --root /path/to/project
+node bin/just-vibe.mjs show auto
+node bin/just-vibe.mjs profiles architecture
+node bin/just-vibe.mjs profile principal-engineer
+node bin/just-vibe.mjs inspect --root /path/to/project
+node bin/just-vibe.mjs discover --root /path/to/project
+node bin/just-vibe.mjs route --root /path/to/project -- "Investigate failing GitHub checks"
+node bin/just-vibe.mjs project show --root /path/to/project
+node bin/just-vibe.mjs project resume checkout --root /path/to/project
+node bin/just-vibe.mjs evidence github --repo owner/repo --pr 42
+node bin/just-vibe.mjs hooks status --root /path/to/project
+node bin/just-vibe.mjs workflow fix --root /path/to/project --mode plan -- "Fix checkout; preserve the API"
+node bin/just-vibe.mjs workflow auto --profile machine-learning-engineer --stdin
+```
+
+`route` suggests candidates for the host agent; it does not execute them or call a model. `workflow` creates a JSON context record on stdout. Use `--stdin` or `--brief-file` to preserve multiline context verbatim. The CLI inventories the shipped payload; native host enablement still applies. It never treats a CLI on PATH as proof of authenticated access.
+
+External capabilities stay unknown until the host observes relevant access or supplied evidence. Explicit capability reports expire after 15 minutes and are bound to a project. The [runtime interface](plugins/just-vibe/references/runtime.md) documents their format and `session create/start/amend/supersede/profile/record/finish/resume`. These utilities validate bookkeeping; they do not sandbox host tools or independently prove the agent's evidence.
+
+Plain `tools` shows a starter selection; `tools --all` lists everything. `route` explains a few candidates; use `--json` for structured context. Project writes require explicit operations and revision-aware JSON input. Evidence collectors have their own prerequisites and do not automatically grant capability status. See [examples and schemas](plugins/just-vibe/references/daily-workflows.md).
+
+## Quick install
+
+You need **Node.js 22+** and **Codex CLI** or **Claude Code** with native plugin support on your `PATH`. See [compatibility and known limits](docs/compatibility.md).
+
+Install the public `just-vibe` package from npm with your preferred package manager:
+
+```sh
+# Choose your package manager; all use the same npm package.
+pnpm dlx just-vibe@latest setup
+npx just-vibe@latest setup
+yarn dlx just-vibe@latest setup
+
+# Claude Code
+pnpm dlx just-vibe@latest setup --target claude
+```
+
+The installer copies the included plugin into a persistent directory under `~/.just-vibe`, then registers it through the host's native plugin manager. The installed files survive npm/pnpm/Yarn cache cleanup. No private GitHub access is required for the default bundled source. `JUST_VIBE_HOME` can select another persistent directory.
+
+**Start a new conversation after installation.** In Claude Code, run `/just-vibe:help what is available?`. In Codex, select the `help` skill from the just-vibe plugin and add your request.
+
+For development builds, users with repository access can fetch the package from GitHub and still use the bundled installer:
+
+```sh
+pnpm --package=git+https://github.com/Zachshotamartin/just-vibe.git dlx just-vibe setup
+```
+
+GitHub access is needed to download that package, but the installed marketplace is a persistent local copy.
+
+## Preview, diagnose, update, remove
+
+```sh
+pnpm dlx just-vibe@latest setup --dry-run
+pnpm dlx just-vibe@latest doctor
+pnpm dlx just-vibe@latest update
+pnpm dlx just-vibe@latest uninstall
+```
+
+Append `--target claude` for Claude Code. `--dry-run` performs no host commands or payload copying and does not inspect installed state; the package manager may still fetch/cache the CLI before it starts.
+
+Repeated `setup` preserves the existing managed version and registration. `update` replaces the managed source with the version in the package you execute and updates the host plugin. Use `@latest` to fetch new releases. `doctor` checks prerequisites, source identity, managed files and enabled installation without changing configuration.
+
+Uninstall removes only this plugin and retains its marketplace, managed source and persistent plugin data. To remove registration too, use the host's native marketplace-removal command after uninstalling. A failed native operation reports partial completion; fix its cause and rerun. Unmanaged destinations, different marketplace sources, and conflicting Claude scopes are never silently overwritten.
+
+## Claude scope
+
+Claude defaults to `user`. From a project's directory, use `--scope project` for shared plugin enablement or `--scope local` for unshared project enablement:
+
+```sh
+pnpm dlx just-vibe@latest setup --target claude --scope project
+```
+
+Pass the same scope to subsequent commands. Each teammate installs their own local marketplace. Codex does not take Claude's `--scope` option.
+
+## Existing GitHub installs and source migration
+
+v0.2 registered GitHub as the marketplace source. Manage that source explicitly with `--github`:
+
+```sh
+node bin/just-vibe.mjs doctor --github
+node bin/just-vibe.mjs update --github
+```
+
+To switch to bundled installation, uninstall using the old source flag, remove only the just-vibe marketplace through the host CLI, then run setup without a source flag:
+
+```sh
+# Codex; use the selected package runner instead of node when outside this checkout.
+node bin/just-vibe.mjs uninstall --github
+codex plugin marketplace remove just-vibe
+node bin/just-vibe.mjs setup
+
+# Claude (preserve any --scope option used for the old installation).
+node bin/just-vibe.mjs uninstall --github --target claude
+claude plugin marketplace remove just-vibe
+node bin/just-vibe.mjs setup --target claude
+```
+
+Use the equivalent `--local` flag when switching from a development checkout. GitHub sources still require Git access; authenticate using your normal Git credentials, never tokens embedded in commands.
+
+## Native install without Node.js
+
+The included skills and plugin manifests can be installed directly. Node.js 22+ is still required for the bundled installer, discovery, run-state, and quiz utilities.
+
+```sh
+# Codex
+codex plugin marketplace add Zachshotamartin/just-vibe
+codex plugin add just-vibe@just-vibe
+
+# Claude Code
+claude plugin marketplace add Zachshotamartin/just-vibe
+claude plugin install just-vibe@just-vibe --scope user
+```
+
+Use one installation channel per host. The wrapper and native commands above manage the same plugin; do not additionally copy skills or merge global rules by hand.
+
+## Local development
+
+```sh
+git clone https://github.com/Zachshotamartin/just-vibe.git
+cd just-vibe
+npm ci
+npm run check
+node bin/just-vibe.mjs setup --local --dry-run
+node bin/just-vibe.mjs setup --local
+```
+
+`--local` registers the persistent checkout directly. Keep the checkout in place. Use `--local` consistently for its `doctor`, `update`, and `uninstall` operations. For changes to the plugin payload, bump the version in both plugin manifests and `package.json`, then run `update --local` and start a fresh conversation.
+
+Switching between bundled, local and GitHub sources is deliberate: uninstall from the old source, remove its marketplace with the host CLI, then run setup for the new source. The installer will not silently replace one with the other.
+
+### Tests and generation
+
+```sh
+npm run check
+npm run test:hosts
+npm run test:hosts -- --github
+npm run eval:runtime
+npm run build:skills
+```
+
+The default checks validate catalogs, generated skills, references, manifests and packaging; test installer/discovery/run behavior; and exercise context preservation across all command names and both host mappings. They do not access your host configuration or make model calls. `test:hosts` is an opt-in native lifecycle test requiring both host CLIs. It runs install, repeat install, doctor, update, uninstall, and reinstall inside temporary `CODEX_HOME` and `CLAUDE_CONFIG_DIR` directories.
+
+The default host test copies and installs the bundled payload. `--local` tests direct checkout registration. `--github` installs the published private repository and requires Git access; use it after pushing a release. Both variants execute the cached plugin runtime and check every skill is present, independently of the source checkout.
+
+Edit `plugins/just-vibe/catalog/commands.json` for command contracts and runtime procedures, `catalog/packs.json` for pack requirements, and `references/packs/` for operational guidance. Run `npm run build:skills` to regenerate skills, the command reference, and evaluation scenarios. `npm run validate` rejects drift. Neither generation nor the installed runtime depends on the ignored local plan.
+
+Every workflow has normal, edge and missing-evidence cases in [evals/scenarios.json](evals/scenarios.json). The [independent behavioral harness](evals/README.md) additionally prepares and grades 21 raw-artifact tasks, including code repairs and report judgments. Catalog structure, runtime utility coverage and observed agent behavior have separate validation fields. These are not claims that all commands have been run against live services or evaluated across models. See the [v0.4 observed results](evals/releases/0.4.0.md) and [evaluation guidance](evals/README.md) for the tested scope.
+
+The [v0.6 results](evals/releases/0.6.0.md) record 32 controlled implementation trials and eight revised-command development trials. All passed their bounded checks; this does not rank overall output quality or convenience. The tasks supplied detailed contracts and did not measure user effort or preference. The [command-depth review](docs/command-quality.md#focused-depth-review) explains 27 focused revisions, and the [contextual review guide](docs/command-quality.md#output-quality-and-convenience) covers judgment, clarity, discovery and correction burden. [Benchmark protocol and supporting metrics](evals/benchmark/README.md) remain available for reproduction. External integration, browser and deployment checks require the relevant task environment.
+
+### Repository layout
+
+| Path | Purpose |
+|---|---|
+| `bin/just-vibe.mjs` | npm-executable entry point |
+| `plugins/just-vibe/scripts/installer.mjs` | Self-contained installer, also shipped inside the plugin |
+| `plugins/just-vibe/scripts/toolkit.mjs` | Search, inspection, discovery, routing candidates, run records, and quiz CLI |
+| `plugins/just-vibe/scripts/lib/` | Catalog, capability, project, run-state, and native quiz adapter modules |
+| `plugins/just-vibe/catalog/` | Canonical command contracts, 112 role profiles, examples, prerequisites and pack metadata |
+| `plugins/just-vibe/skills/` | 215 installed names, including three canonical aliases and setup |
+| `plugins/just-vibe/references/` | Shared execution rules, runtime interface, domain guidance and command index |
+| `.agents/plugins/marketplace.json` | Codex marketplace |
+| `.claude-plugin/marketplace.json` | Claude Code marketplace |
+| `scripts/` and `tests/` | Validation and lifecycle tests |
+| `evals/` | Behavior scenarios and isolated project/data fixtures |
+
+The installer has no runtime npm dependencies or lifecycle install scripts. Optional bundled hooks do no work until configured and trusted for a project; native host trust also applies. It adds no MCP servers, rules or permissions. Provider/check commands use argument arrays rather than interpolating user input into a shell. Host CLIs own installation state and caches. Local planning and naming documents are excluded from both Git and the npm archive.
+
+## Troubleshooting
+
+- **Host executable not found:** install the selected CLI and reopen your terminal.
+- **Plugin subcommands unavailable:** update that host CLI; just-vibe checks command support before changing state.
+- **Repository not found / authentication failed:** verify `git ls-remote https://github.com/Zachshotamartin/just-vibe.git` succeeds with your account.
+- **Different marketplace source:** use the matching bundled, `--local`, or `--github` setting or explicitly switch sources as described above.
+- **Claude scope conflict:** inspect `claude plugin list --json`; manage the scope already in use rather than layering installations.
+- **Skills not visible:** verify with `doctor`, then start a new conversation.
+
+Host formats evolve. When a JSON inventory format is unrecognized, the installer stops rather than guessing how to change configuration.
+
+## Release and license
+
+Licensed under [MIT](LICENSE), copyright 2026 Zachary Martin. Commercial use, modification and redistribution are allowed under the license terms. The license ships with the npm archive and installed plugin.
+
+[Release instructions](docs/releases.md) describe validation, the first npm publication, trusted publishing, versioning and recovery. [Changelog](CHANGELOG.md) records user-visible changes.
+
+Command authoring and alias maintenance follow the [command quality contract](docs/command-quality.md).

package/bin/just-vibe.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from '../plugins/just-vibe/scripts/toolkit.mjs';
+process.exitCode = await main(process.argv.slice(2));

package/docs/command-quality.md

@@ -0,0 +1,74 @@
+# Command contracts and quality
+
+The catalog owns each canonical command's scope, mode, required inputs, selection boundary, procedure, decision branches, outputs, observable verification, recovery conditions and examples. Pack references add reusable methods and worked scenarios. Generated SKILL.md files expose all examples and link the applicable guide; they are not independently edited.
+
+215 names resolve to 212 canonical workflows. `do` inherits `auto`, `responsive` inherits `ui-responsive`, and `a11y` inherits `ui-accessibility`. Alias source records contain identity/search metadata only. Loading materializes the canonical behavior; validation rejects scope, mode, method, evidence or other behavioral drift. Routing collapses matching aliases to one canonical recommendation while preserving matched names.
+
+## Writing useful guidance
+
+Selection should distinguish a nearby workflow: explain versus teach, debug versus fix, local pr drafting versus remote github-pr identity/actions. A task-specific procedure should name the evidence to inspect and the decision it informs. A branch should cover a situation that changes the method, such as a partial external operation, incompatible old consumer, stale request completion or missing evaluation labels.
+
+Outputs need enough structure to assess correctness: a comparison needs assumptions and decisive evidence; a migration needs ordered phases, compatibility and recovery boundaries; an audit needs observed/conditional/unknown findings. Normal, edge and missing-evidence requests demonstrate scope and input handling. They do not count as successful evaluations by existing in the catalog.
+
+Keep generic execution rules in the shared guide. Use current primary documentation when behavior depends on framework/provider version. Do not copy a full manual into every command or turn a particular incident into a universal rule. Short commands are acceptable when the task is simple and the contract is clear.
+
+## Output quality and convenience
+
+The product question is whether a workflow helps someone get useful work done with less preparation and correction. Correctness checks can establish specific behavior; they cannot fully score architectural judgment, communication or convenience. More instructions, commands, tests or tokens are not evidence of a better experience by themselves.
+
+Use contextual review alongside executable checks. Record concrete examples and the reviewer's task and preferences; avoid converting unlike judgments into an overall product score.
+
+| Dimension | Review the actual experience | Useful evidence |
+| --- | --- | --- |
+| Task fit and judgment | Did the agent address the real need with proportionate scope and sensible tradeoffs? | Accepted result, unnecessary work, assumptions and decisions the user changed |
+| Maintainability | Does the implementation fit the repository and remain understandable to its maintainers? | Reviewer comments tied to code and existing conventions |
+| Clarity | Can the user understand what changed, why and what remains uncertain? | Statements checked against artifacts; confusing or missing explanations |
+| Discovery | Could the user find a suitable command or profile without learning the catalog? | Initial request, route selected, search detours and mistaken selections |
+| Context and correction burden | How much did the user have to specify, repeat or repair? | Starting brief, consequential follow-ups and corrections, with their reasons |
+| Defaults and control | Did the workflow choose helpful defaults while honoring the user's boundaries? | Decisions accepted or overridden, avoidable interruptions and scope changes |
+
+For a practical comparison, use the same realistic starting brief, model and repository revision; let each toolkit use its documented native setup. Include routine and unfamiliar tasks with the amount of context a user would normally provide. Evaluate both first use and repeat use: setup and discovery costs can differ from day-to-day usefulness. Preserve failed attempts and corrections. Where feasible, review anonymized outputs before revealing the toolkit, then collect the user's preference and reasons. Identify the reviewer and task context without publishing private information. Counts of follow-ups or elapsed time are supporting observations: a necessary clarification can improve quality, and a shorter interaction can hide a bad assumption.
+
+The [v0.6 repository study](../evals/releases/0.6.0.md) supplied complete written contracts, so it barely exercised discovery or context burden. It provides narrow implementation evidence and no measured user preference or convenience result. Token usage is supporting operational data, not the objective or a quality score.
+
+## Focused depth review
+
+The v0.6 review replaces repeated procedure/output sentences in 27 contracts with decisions that change agent behavior. It improves the shared execution guide for every workflow, but does not claim all 212 canonical workflows have been independently behavior-tested.
+
+| Area | Revised commands | Missing detail addressed |
+| --- | --- | --- |
+| Repair and testing | `fix`, `test-regression` | Read the actual contract; derive expectations independently; preserve user work during negative testing; inspect real exit statuses |
+| Shared backend state | `backend-cache`, `backend-concurrency`, `backend-idempotency`, `db-integrity` | Waiter versus shared-work lifetime, generation invalidation, transaction ownership, strict input/range checks, partial failure and replay |
+| Historical ML data | `ml-features`, `ml-split` | Visible-version selection before window filtering, label maturity before preprocessing, offset-aware instants, unknown versus zero labels |
+| React state/lifecycle | `react-async`, `react-effects`, `react-hydration` | Stale error as well as success, disposal, shared subscribers, matching initial render and request isolation |
+| Git and GitHub | `git-commit`, `github-pr`, `github-actions` | Candidate-tree checks, preservation of three-tree differences, PR identity after uncertain creation, SHA-specific readiness and trust/event paths |
+| Delivery | `db-migrate`, `vercel-build-fix`, `vercel-release-check` | Old/new writer compatibility, restart and recovery limits, first causal build failure, deployment-specific gates |
+| Frontend delivery and interaction | `vite-bundle`, `vite-assets`, `ui-accessibility` | Comparable size/performance evidence, nested/base-path assets and content types, keyboard/focus transitions and actual AT coverage |
+| Architecture | `arch-feature`, `arch-boundaries`, `arch-scale` | Requirement-to-owner reasoning, contracts that enforce boundaries, measured bottlenecks and bounded capacity claims |
+| Decisions | `decide`, `decision-spike` | Unknown feasibility, sensitivity, decisive experiments and thresholds set before observing results |
+| LLM systems | `llm-evals`, `llm-tools` | Scorer controls, retained failures/denominators, held-out limits, typed effects and uncertain-call reconciliation |
+
+The four repeated benchmark tasks cover selected command bundles, not every command in this table. The other revisions are instruction-review improvements with structural and packaging checks. Keep that distinction in release claims.
+
+For future reviews, ask whether a competent agent could follow the guidance without inventing a consequential policy. Add detail when ownership, timing, authority, recovery or verification is ambiguous. Remove text when it merely restates the summary. Prefer a conditional worked example in a pack guide over repeating a full procedure in every related skill.
+
+Useful next evaluations include authenticated deployment recovery in an isolated test project, browser interaction and assistive-technology tasks, API compatibility across consumer versions, and real repository changes under a fixed issue/revision. These require their actual environments; the present laboratory fixtures do not substitute for that evidence.
+
+## Change process
+
+1. Edit `plugins/just-vibe/catalog/commands.json` and the relevant pack guide.
+2. For an alias, edit its canonical target; keep only identity fields in the alias source.
+3. Run `npm run build:skills` and `npm run check`.
+4. Add or revise a raw-artifact behavioral fixture for a meaningful new decision or failure mode. Keep its expected result in evaluator-only files.
+5. Run a fresh independent agent trial, inspect its actions and grade the actual result. Preserve failures and record instruction/input identities.
+6. Update behavioral validation only for the named commands and fixtures actually evaluated. Keep native-host, browser, external-service and model-quality claims separate.
+
+The schema verifies the presence and shape of this contract, not the quality of its prose. The independent fixtures and review of actual agent decisions provide the stronger evidence.
+
+## Profiles and ownership
+
+`catalog/profiles.json` owns role guidance independently of action contracts. Maintain a distinct purpose, priorities, a decision rule, relevant verification, a boundary and valid canonical workflow links for each role. Generate the profile index and individual references with the same build command. A title alone is not a useful profile; nearby roles must change emphasis in an explainable way.
+
+Test profile state transitions for pin protection, scope and budget preservation. Keep role discovery separate from activation. Do not claim that structural validation proves role expertise or that previous workflow trials evaluate newly added role guidance.
+
+All generated work belongs to the user. Shared execution and Git/GitHub guidance prohibit agent self-attribution in commits, PRs and messages while preserving human credits and required third-party notices.

package/docs/compatibility.md

@@ -0,0 +1,29 @@
+# Compatibility and support
+
+The runtime requires Node.js 22 or newer. CI exercises Node 22 and 24 on Linux, macOS and Windows, including an extracted npm archive. npm, pnpm 10.14.0/12.5.1 and Yarn 4.18.0 execution checks run on Node 24. Node 26 is also used for local development checks.
+
+Real native Codex/Claude plugin lifecycle checks are performed separately on macOS. Windows and Linux CI checks validate the toolkit and packaging; they do not establish native agent-host support. On Windows, use a host CLI that supports native plugins. Native executables and standard npm-generated Node `.cmd` shims are supported; other batch wrappers are rejected with guidance rather than interpreted as shell code. WSL can use the Linux setup path when the selected host supports it. Host and operating-system support remain subject to the host's own requirements.
+
+The default install copies bundled files into `~/.just-vibe/marketplaces/codex` or `~/.just-vibe/marketplaces/claude`. Set `JUST_VIBE_HOME` to use another persistent base directory and retain that setting for future commands. Setup does not require GitHub access. Git is needed for the optional `--github` source and workflows that use Git.
+
+A project-scoped Claude installation still uses a per-user marketplace source; each teammate runs setup on their own machine. No machine-specific path is written into shared project settings by just-vibe itself.
+
+Updates use the package version you execute. Use `pnpm dlx just-vibe@latest update`, `npx just-vibe@latest update`, or `yarn dlx just-vibe@latest update` to retrieve the newest published payload. `setup` preserves an existing managed version. Uninstall retains the managed source, marketplace registration and persistent plugin data.
+
+Capabilities such as GitHub, Vercel, databases, deployment and training require the user's own tools/access. Installation does not authenticate these services. A CLI on PATH does not establish authorization or usable credentials.
+
+`teach-test` requires a native question tool available and permitted for assessment in the current host mode. Real Claude interaction was verified in v0.2; the tested Codex mode restricted question tools to clarification/planning and correctly declined the quiz. ML findings still require review; the previous Claude leakage fixture had a partial behavioral result. See the [v0.2 validation record](../evals/releases/0.2.0.md).
+
+The v0.4 release adds 21 passing supplied-instruction Codex fixture trials and a three-case matched comparison that tied across all arms. These results do not establish native invocation or Claude parity for those workflows. See the [v0.4 validation record](../evals/releases/0.4.0.md).
+
+## v0.5 profile support
+
+The profile/profile-discovery skills and all 112 role guides ship in both host payloads. Profile selection is task context: user pins are protected by the run-state utilities, and no host-global preference is installed. Native installation checks cover the 215-skill payload; they do not establish profession-specific agent behavior. See the [v0.5 validation record](../evals/releases/0.5.0.md).
+
+## v0.7 daily workflow support
+
+Project state and contextual routing use the bundled Node utilities on all supported runtime platforms. State is schema-versioned and bound to the selected project path. Partial snapshot coverage always requires revalidation. `tools` now shows a starter selection; use `tools --all` for the previous full inventory.
+
+Optional hooks use PostToolUse and Stop and ship at the native plugin hook location. They remain inactive until project configuration and separate local trust are present. Codex also requires native hook trust. Native installation on macOS is verified separately from actual hook-event delivery on every host/OS. A direct hook runner test establishes handler behavior, not host parity. Command arrays support native executables and standard npm Windows wrappers through the shared process helper.
+
+GitHub evidence needs authenticated gh; Vercel evidence needs authenticated vercel and an explicit deployment identity. Browser evidence needs project-installed Playwright and Chromium, with authorized interactions. SQL migration evidence inspects local SQL and an optional supplied applied-history export; it does not connect to a live database. The package installs no optional provider or browser dependencies automatically. See the [daily workflow reference](../plugins/just-vibe/references/daily-workflows.md).

package/docs/releases.md

@@ -0,0 +1,51 @@
+# Releasing just-vibe
+
+Releases use the public `just-vibe` package on npm. A prepared archive is not a published package: verify the exact version and archive integrity in the registry after publication.
+
+## Check and package
+
+Use Node.js 24 and npm. From a clean checkout:
+
+```sh
+npm ci --ignore-scripts
+npm run release:check
+npm run release:prepare
+```
+
+`release:check` runs catalog/manifests/generated-file validation, unit and packaging tests, version/license/changelog checks, archive allowlisting, relative-link checks, and common credential-pattern checks. These checks cannot prove the absence of every secret or software defect; review the file list and diff too.
+
+`release:prepare` performs those checks, creates `dist/just-vibe-VERSION.tgz`, executes that exact archive through npm, pnpm 10/12 and Yarn 4 in temporary projects, checks persistence after cache removal, and writes a SHA-256 checksum plus a source-commit release record. It does not publish. Test helpers download pinned package-manager executables into temporary directories and do not replace your global tools.
+
+For installer changes, also run `npm run test:hosts`. This uses the real installed Codex and Claude CLIs with temporary configuration and managed-copy directories. It does not use your normal plugin configuration or call a model. Run `npm run test:hosts -- --local` for the development channel, and `-- --github` only after pushing the same version (private Git access required).
+
+The `prepublishOnly` hook runs `release:check` for directory-based `npm publish`. Publishing a tarball or using `--ignore-scripts` bypasses that hook. The release workflow separately validates the archive before using either.
+
+## First publication
+
+1. Create/sign into the npm account that will own `just-vibe` and enable 2FA. Check name availability again immediately before publishing.
+2. Review the MIT license and release notes, commit the release, and wait for every CI job at that commit to pass. Native host validation is recorded separately; CI does not log in to agent accounts.
+3. Run `npm login`, then `npm whoami`. Do not paste tokens into the repository or chat.
+4. Run `npm run release:prepare`, review the archive, and run `npm run release:publish -- --check`. This checks the clean source commit, prepared archive, completed CI and npm login. Then run `npm run release:publish -- --publish` and complete npm's authentication prompt. The command verifies registry integrity and exact-version execution; it reconciles an uncertain response without automatically retrying publication.
+5. Verify the exact version using `npm exec --yes --package=just-vibe@VERSION -- just-vibe --version`; test setup in a clean host profile, then create the matching `vVERSION` Git tag.
+
+Only publish code/assets you have the rights to distribute. Retain third-party notices if third-party code is added later. The current npm package has no runtime dependencies. All included code and workflow documents are covered by the included MIT notice unless a file states otherwise.
+
+## Subsequent GitHub releases with trusted publishing
+
+After the package exists, configure its npm **Settings → Trusted publishing**:
+
+- GitHub owner: `Zachshotamartin`
+- Repository: `just-vibe`
+- Workflow filename: `publish.yml`
+- Environment: leave blank (the workflow does not declare one)
+- Allow direct `npm publish` for this workflow.
+
+The workflow uses Node 24 and npm 12 with OIDC. It needs no long-lived npm token. Private GitHub repositories can publish public packages; npm provenance is disabled for private repositories because npm cannot generate it from private source. The workflow enables provenance automatically if the repository is later made public.
+
+Update `package.json`, both plugin manifests, the lockfile, and `CHANGELOG.md` together. Follow semantic versioning; during 0.x development, document breaking changes explicitly and increment the minor version. Published versions cannot be reused.
+
+Push the release commit and matching `vVERSION` tag. Run **Publish npm package** from that tag with **publish** checked. All six platform/Node checks must pass; the release job then builds and tests the exact archive, checks its checksum and tag, and publishes it. Leaving **publish** unchecked performs a rehearsal without publishing. Ordinary pushes and PRs never publish.
+
+If publication fails, check whether that exact version already exists before retrying. A successful upload followed by a failed verification still consumes the version. If a bad release is already live, publish a corrected new version and deprecate the affected one with a clear explanation.
+
+Official references: [npm publishing](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages/), [trusted publishing](https://docs.npmjs.com/trusted-publishers/), [semantic versioning](https://docs.npmjs.com/about-semantic-versioning/).

package/evals/README.md

@@ -0,0 +1,47 @@
+# Evaluating just-vibe
+
+Validation has three separate dimensions in the catalog:
+
+- `structural: automated`: contracts, generation, references and packaging are checked.
+- `runtime: fixtures-tested | not-applicable`: deterministic utilities have relevant fixture coverage. This does not measure an agent's judgment.
+- `behavioral: not-evaluated | passed-fixtures | partial-fixtures`: observed agent outcomes on named bounded fixtures. Evaluated entries name an evidence record; no label means universal reliability or host parity.
+
+The generated [scenarios.json](scenarios.json) supplies normal, edge and missing-evidence invocations plus evidence requirements and a rubric for all 215 skill names. These are specifications, not completed model runs. Aliases inherit their canonical contract and validation.
+
+## Independent behavioral fixtures
+
+[behavior/cases.json](behavior/cases.json) defines 21 raw-artifact tasks. Their inputs and task briefs are separate from [evaluator oracles](behavior/oracles.json). The harness copies only raw task files and selected instructions into an isolated workspace. It never copies grading answers into that workspace. Expected facts and executable behavior assertions were authored independently of generated command wording.
+
+Prepare a fresh trial:
+
+```bash
+npm run eval:behavior -- prepare --case react-race --out .tmp/trials/react-race
+```
+
+Give an independent agent only the resulting `prompt.txt` and its referenced workspace. It must preserve supplied files except the explicitly allowed implementation targets and write `answer.json` outside the workspace. Do not show it evaluator oracles or previous trial answers. Local code checks are permitted by the task; network, installations, external mutations and further delegation are excluded from these fixtures.
+
+Grade afterward:
+
+```bash
+npm run eval:behavior -- grade --run .tmp/trials/react-race
+```
+
+The grader verifies input/instruction hashes, permitted changed files, independently specified factual judgments, and relevant executable assertions. Regression-test evaluation runs the authored test against the correct implementation and two independent mutants, rejecting vacuous tests. Report inspection checks verify explicit judgments against supplied facts; the reasoning prose still requires human review. Executable grading runs reviewed local fixture code; this harness is not a sandbox for hostile submissions.
+
+`npm run eval:behavior -- list` shows available cases. `npm run check` checks the harness itself against seeded wrong reports, broken code, vacuous tests and correct controls. Those synthetic harness checks are **not** model trials. It does not call models or services.
+
+## Controlled comparisons
+
+Prepare the same case in three fresh directories with `--arm baseline`, `--arm just-vibe`, or `--arm ecc --ecc-root /path/to/pinned/ECC`. ECC supports cases with a declared matched source file in the manifest. Record the ECC revision before preparation. The comparator supplies that matched guide, not ECC's complete installed hooks/agents/runtime; name this limitation when interpreting results.
+
+Keep model, effort, host tools, task artifacts, action permissions and budget equal. Use separate fresh agent contexts, randomize order for a larger study, repeat trials, and retain failures. Record source/prompt hashes, changed files, checks, host/model settings and actual usage/timing from host logs. Do not infer cost from elapsed preparation time. A small tied comparison demonstrates no superiority; a single observed difference needs replication.
+
+Results should distinguish task correctness, unsupported claims, unrequested edits, completion, elapsed execution time, tokens and verified cost. Unsupported metrics remain unavailable. Keep development fixtures separate from future held-out benchmark tasks; public fixtures are useful regressions but are not a durable blind benchmark.
+
+## Existing evidence and limits
+
+The [repeated repository benchmark](benchmark/README.md) adds fresh multi-file tasks, matched baseline/just-vibe/profile/ECC arms, randomized repeated runs and native CLI usage/timing capture. Its controlled correct/defective implementations test the scorer without model calls. Run model trials explicitly; `npm run check` does not consume account usage. These new fixture repositories are authored test environments, not a production-repository benchmark or a full native ECC installation.
+
+The [v0.2 record](releases/0.2.0.md) contains native Codex/Claude trials, including a partial Claude leakage audit and the tested Codex mode's unavailable native assessment dialog. Later instruction changes do not retroactively turn those trials into passes.
+
+The original [checkout](fixtures/checkout/) and [ML](fixtures/ml/) fixtures remain available. `npm run test:hosts` verifies native installation lifecycles in isolated host configuration directories. It does not establish model behavior, authenticated deployments, database execution, browser rendering or training quality. These need separately identified environments and evidence.

package/evals/behavior/cases/arch-events/flow.json

@@ -0,0 +1,12 @@
+{
+  "producer": [
+    "commit order in database",
+    "publish event to independent broker"
+  ],
+  "consumer": [
+    "send email without idempotency key",
+    "acknowledge message"
+  ],
+  "atomicDatabaseBrokerCommit": false,
+  "redelivery": true
+}