Vibe Governed Runtime Entry

This file is the host-facing SOP for entering canonical vibe. Keep it small: runtime details belong in protocols/runtime.md, execution discipline belongs in protocols/do.md, and host wrapper recipes belong in installer-generated wrapper docs.

Trigger Contract

Enter canonical vibe before ordinary execution when the user explicitly invokes $vibe, /vibe, or the vibe skill, or when the host intentionally chooses governed requirement/plan/execution closure for a complex task.

Do not route every loosely related task into vibe. Lightweight questions, single-command checks, or tasks better served by another explicitly requested skill may proceed outside vibe unless the user explicitly invoked this entry.

vibe-upgrade is a separate public skill for upgrading the installed Vibe-Skills project. Do not relaunch an upgrade request as entry_id = vibe; use the vibe-upgrade skill and its backend instead.

User instructions remain highest priority. If CLAUDE.md, GEMINI.md, AGENTS.md, or the direct user request narrows or forbids a workflow such as TDD, follow the user's instruction while preserving canonical launch and proof rules.

Canonical Launch SOP

Before canonical launch, do only the minimum needed to launch:

Resolve skill_root: the directory containing this SKILL.md.
Resolve workspace_root: the task workspace where governed artifacts should be written.
Resolve host_id: codex, claude-code, cursor, windsurf, openclaw, or opencode.
Extract core intent as keyword text. Do not pass the raw prompt, full chat history, or mixed-language filler to the router.

Do not inspect repository files, protocol docs, previous run outputs, or old proof artifacts before canonical launch returns. Reading this file, a wrapper, or an AGENTS/CLAUDE bootstrap block is not proof of canonical entry.

Internal specialist recommendation router: scripts/router/resolve-pack-route.ps1

Specialist recommender input rules:

This recommender runs inside canonical vibe; it may suggest specialist skills, but it does not decide whether $vibe is the public runtime entry.

Include work type, domain/technology, deliverable, and explicit constraints.
Reuse verified frozen requirement/plan facts when continuing a run.
If the router returns confirm_required, surface the machine-readable route contract and convert the user's natural-language reply into a structured route decision.
If the router fails, report blocked with the concrete failure reason.

Canonical entry command shape:

$env:PYTHONPATH = "<skill_root>/apps/vgo-cli/src"
py -3 -m vgo_cli.main canonical-entry `
  --repo-root "<skill_root>" `
  --artifact-root "<workspace_root>" `
  --host-id "<host_id>" `
  --entry-id "vibe" `
  --prompt "<extracted keyword intent text>"

Bash-like hosts, including Claude Code, should avoid Bash-wrapped PowerShell. Set PYTHONPATH in the outer shell and call Python directly:

REPO_ROOT='<skill_root>'
WORKSPACE_ROOT="${WORKSPACE_ROOT:-$PWD}"
PYTHONPATH="$REPO_ROOT/apps/vgo-cli/src" py -3 -m vgo_cli.main canonical-entry \
  --repo-root "$REPO_ROOT" \
  --artifact-root "$WORKSPACE_ROOT" \
  --host-id "<host_id>" \
  --entry-id "vibe" \
  --prompt "<extracted keyword intent text>"

After canonical-entry returns a session_root, validate proof artifacts only inside that launched session:

host-launch-receipt.json
runtime-input-packet.json
governance-capsule.json
stage-lineage.json

Bounded Stop And Re-entry

vibe uses progressive governed stops:

requirement_doc
xl_plan
phase_cleanup

When bounded_return_control.explicit_user_reentry_required = true, stop the current assistant turn. Do not consume re-entry credentials until a later user message approves or revises the current boundary.

For re-entry, inspect runtime-summary.json -> bounded_return_control.host_decision_contract, infer the user's intent, and write a structured host decision JSON file. Use the same run_id, bounded_reentry_token, and stable workspace_root:

REPO_ROOT='<skill_root>'
WORKSPACE_ROOT="${WORKSPACE_ROOT:-$PWD}"
DECISION_JSON="$WORKSPACE_ROOT/.vibeskills/tmp/host-decision.json"
mkdir -p "$(dirname "$DECISION_JSON")"

cat > "$DECISION_JSON" <<'JSON'
{
  "decision_kind": "approval_response",
  "decision_action": "approve_requirement",
  "approval_decision": "approve"
}
JSON

PYTHONPATH="$REPO_ROOT/apps/vgo-cli/src" py -3 -m vgo_cli.main canonical-entry \
  --repo-root "$REPO_ROOT" \
  --artifact-root "$WORKSPACE_ROOT" \
  --host-id "<host_id>" \
  --entry-id "vibe" \
  --prompt "<stable continuation intent, not just the user's short reply>" \
  --continue-from-run-id "<source_run_id>" \
  --bounded-reentry-token "<reentry_token>" \
  --host-decision-json-file "$DECISION_JSON"

A structured approval advances to the next progressive stop. A structured revision must include non-empty revision_delta and refreezes the same bounded stage without asking the user for a separate approval first:

{
  "decision_kind": "approval_response",
  "decision_action": "revise_requirement",
  "approval_decision": "revise",
  "revision_delta": [
    "Freeze one public small/medium face dataset downloaded locally.",
    "Require a polished LaTeX paper and compiled PDF."
  ]
}

Route confirmations must stay inside surfaced confirm options. Bounded approvals or revisions must stay inside the surfaced bounded-stage action contract.

Runtime Contract Summary

Canonical vibe owns one runtime authority and one visible requirement/plan surface. The fixed state machine is:

skeleton_check
deep_interview
requirement_doc
xl_plan
plan_execute
phase_cleanup

These stages may be light for simple work, but they are not silently skipped. The full runtime contract, stage ownership, lineage rules, internal M/L/XL grades, cleanup rules, and output inventory are defined in protocols/runtime.md.

Public wrapper entries remain limited to:

vibe
vibe-upgrade

Compatibility stage IDs are non-public metadata and must not be materialized as host-visible command or skill wrappers:

vibe-what-do-i-want -> requirement_doc
vibe-how-do-we-do -> xl_plan
vibe-do-it -> phase_cleanup

Skill Execution

The router may surface selected skill execution candidates, but vibe remains the runtime-selected skill and runtime authority.

The host must inspect surfaced candidates and make a structured skill execution decision when curation is needed. It may approve, defer, or reject only surfaced candidate ids. Unsuitable or noisy candidates should be rejected or deferred with a reason rather than forced into execution.

Only selected skills become execution units. The host must not invent unsurfaced skills, bypass runtime validation, create hidden skill sub-sessions, or open a second requirement/plan/runtime surface. Selected skill work must preserve the skill's own workflow, inputs, outputs, and validation style.

For XL delegation, root/child hierarchy remains governed: only root_governed may freeze canonical requirements/plans or make final completion claims. child_governed lanes inherit the frozen context, stay inside assigned write scopes, validate delegation-envelope.json, and emit local receipts only.

Quality Rules

Never claim success without evidence. Minimum invariants:

Verify before completion.
Do not make silent no-regression claims.
Keep requirement and plan artifacts traceable to the launched run.
Emit cleanup receipts before claiming phase completion.
Expose failures, fallback, degraded status, or blocked state explicitly.
Do not add mock success paths, swallowed errors, or template-only pass results.
Do not use fallback or boundary behavior to bypass real execution, verification, or root-cause repair.

Protocol Map

Read these references only after canonical launch or whe

vibe