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.
Installed-copy updates use update --skills-dir <skills-dir> on the same managed directory.
User instructions, including CLAUDE.md, GEMINI.md, AGENTS.md and direct workflow limits such as TDD exceptions, remain highest priority. Preserve canonical launch and proof rules within those limits.
Canonical Bootstrap
vibe is a host-syntax-neutral skill contract. Before canonical launch, do only the minimum needed to launch:
- Resolve
skill_root and workspace_root.
- Pass the current user task verbatim as the task specification; unrelated chat history may be excluded. Do not summarize, rewrite, or reduce it to keywords. Preserve exact input paths, input immutability constraints, exact output roots, synthetic-data evidence boundaries, module dependencies and safe parallel boundaries, and acceptance criteria.
Do not search the current workspace, repository, or install root for canonical proof files before launch.
Do not inspect the repo, protocol docs, or prior run outputs before canonical launch returns.
Do not simulate stages, claim canonical entry from reading this file or wrapper text, or treat wrapper or AGENTS text as proof.
Do not manually create outputs/runtime/vibe-sessions/<run-id>/.
Do not use the Vibe installation root as the governed artifact root.
Local skill candidate audit: semantic owner packages/runtime-core/src/vgo_runtime/router_contract_runtime.py; compatibility bridge scripts/router/resolve-pack-route.ps1
The audit runs inside canonical vibe and exposes candidates for inspection. Include work type, domain/technology, deliverable, explicit constraints, and verified frozen facts on continuation. Its output is compatibility evidence only; the Agent owns skill choice, binding, and stage progression.
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>" --prompt "<current user task, verbatim>"
For PowerShell, do not place $env:PYTHONPATH=... inside a double-quoted -Command string; host interpolation may corrupt it to :PYTHONPATH.
Bash-like hosts, including Claude Code, set PYTHONPATH in the outer shell and call Python directly. Try py -3, python, then python3 according to availability.
REPO_ROOT='<skill_root>'
WORKSPACE_ROOT="${WORKSPACE_ROOT:-$PWD}"
PYTHONPATH="$REPO_ROOT/apps/vgo-cli/src" python -m vgo_cli.main canonical-entry --repo-root "$REPO_ROOT" --artifact-root "$WORKSPACE_ROOT" --prompt "<current user task, verbatim>"
--host-id and --entry-id remain compatibility-only for wrappers or older automation; omit them on a normal launch.
Only validate canonical proof artifacts after canonical-entry returns a session_root.
check proves installed locally; runtime coherence and delivery acceptance require their own evidence.
Proof of canonical launch is post-launch and requires: host-launch-receipt.json, runtime-input-packet.json, governance-capsule.json, and stage-lineage.json under the returned session_root.
local-agent-kernel follows the same proof rule. If it cannot produce those truth artifacts, it may produce local work scaffolds, but it must not be treated as canonical verified.
If canonical launch fails, report blocked with the concrete failure reason instead of simulating the missing stages or proof artifacts.
Consensus And Task Evolution
Use deep_interview until the user and Agent agree on the goal, scope, constraints, deliverables, relevant unknowns, and completion criteria. Freeze the requirement after confirmation of that task-specific summary; the first clarification is an input to the conversation.
Keep the agreement in the existing TaskCard. Append accepted revisions, update affected work and checks, and reuse results only while their inputs and acceptance remain valid. Surface decisions that change the agreed outcome, scope, risk, or required human judgment.
Hard Stop And Re-entry
The progressive governed stops are requirement_doc, xl_plan, and 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.
This is a hard runtime boundary, not a suggestion. It overrides ordinary host
autonomy rules such as "continue until done." A detailed original request is not
approval of the frozen requirement or frozen plan. After a hard stop, do not
perform equivalent manual work outside governed re-entry: no plan writing, task
execution, manual workaround delivery, or final artifact delivery in the same
assistant turn.
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:
At a requirement stop, build agent_skill_organization directly from agent_skill_organization_contract; preferred_payload is incomplete until then, and the schema must not be learned through failed retries or runtime source inspection.
Use the same REPO_ROOT and WORKSPACE_ROOT from bootstrap:
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",
"agent_skill_organization": {
"schema_version": "agent_skill_organization_v1", "derived_by": "agent", "workflow_level": "L",
"modules": [{"module_id": "module-a", "goal": "...", "candidate_skill_ids": ["skill-a"], "depends_on": [], "execution_mode": "skill_assigned", "acceptance_criteria": [{"criterion_id": "module-a-result", "description": "The module result satisfies the frozen requirement.", "verification_mode": "automated"}]}],
"selected_skills": [{"skill_id": "skill-a", "module_ids": ["module-a"], "responsibility": "...", "reason": "..."}],
"uncovered_modules": [],
"workflow_level_contract": {"L": "smallest complete organization", "XL": "bounded multi-lane organization"}
}
}
JSON
PYTHONPATH="$REPO_ROOT/apps/vgo-cli/src" py -3 -m vgo_cli.main canonical-entry \
--repo-root "$REPO_ROOT" \
--artifact-root "$WORKSPACE_ROOT" \
--prompt "<current user task, verbatim>" \
--continue-from-run-id "<source_run_id>" \
--bounded-reentry-token "<reentry_token>" \
--host-decision-json-file "$DECISION_JSON"
A structured approval from a later user message 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": ["Use the revised dataset and agreed output scope."]
}
Bounded approvals or revisions must stay inside the surfaced bounded-stage action contract.
At requirement_doc, read runtime-summary.json -> host_user_briefing and use host_user_briefing.rendered_text as the backbone of the user reply. Keep the same field order.
Frame that stop around the Agent-led skill search guide: split the task into modules, search local skills per module, read candidate SKILL.md, organize both L / XL plans, and disclose uncovered modules honestly. Do not surface shortlist size, selected-skill rankings, or raw router ordering at requirement freeze.
Do not ask the user to choose L or XL until the reply explains each task-specific workflow and names the task-specific candidate skill names for that option. Label every named skill as a candidate that is not yet selected or used; formal selection still belongs to the Agent organization produced after requirement approval.
After requirement approval, the Agent must split the approved work into modules, search every declared local skill root for each module, and read each retained candidate's SKILL.md. The host must, before entering xl_plan, put the validated result in HostDecisionJson.agent_skill_organization; route output may remain candidate audit evidence but cannot populate this field. If one selected Skill owns multiple modules, include one module_assignments entry per module with the exact module id, an owner, support, or verifier role, module-specific responsibility, one concrete write scope, expected outputs, and verification. Role order is executable: support runs before and feeds the owner; verifier runs only after the owner. A post-owner review or minimality check must use verifier, not support. An agent_direct module must declare its own concrete write_scope, expected_outputs, and verification; the runtime must not replace them with a generic module label or restated goal. A task work scope must not claim canonical runtime artifacts such as module-execution.json; use a stable task-owned output scope or no task-file writes for read-only work. A plan revision that changes modules, Skills, roles, dependencies, write scopes, outputs, verification, or workflow level must resubmit the complete updated agent_skill_organization; revision_delta alone records text and does not mutate the frozen organization.
Use the directory name that directly contains the retained SKILL.md as the exact skill_id in both candidate_skill_ids and selected_skills[].skill_id. A displayed Skill name or frontmatter name is descriptive, not an execution identifier. A nested retained SKILL.md uses its own containing directory name. Resolve this from the candidate path before submission instead of learning the identifier through failed retries.
Module acceptance criteria must be satisfiable before canonical module-result re-entry. They must not require cleanup receipts, delivery acceptance, or completion-language permission, because canonical phase_cleanup creates those only after module-execution.json is accepted. Verify ordinary modules from their actual deliverables and normal command or test output. Do not invent task-specific hashes, receipts, ledgers, matrices, scans, or proof files solely to prove execution order, Skill use, or file scope. Only require an extra evidence artifact when the user or domain contract needs that artifact.
After plan approval, reuse the frozen agent_skill_organization for plan_execute and cleanup, and do not rerun procedural skill selection, silently add skills, or replace declared gaps unless the user revises the frozen requirement or plan. stage_order records dependency depth, not permission to run in parallel; L still emits one-unit sequential waves even when independent units share a dependency stage. XL may place at most two dependency-ready units in one wave, and nested or overlapping write scopes must remain serial.
After the required plan confirmation, continue through dependency-ready work
without asking for routine permission between units. Give concise progress
updates at meaningful boundaries. If the user revises the agreed task, record
the revision and replan only the affected work before continuing.
Unified Runtime Contract
Canonical vibe owns one runtime authority and one visible requirement/plan
surface. The fixed state machine is:
skeleton_checkdeep_interviewrequirement_docxl_planplan_executephase_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, user-visible L/XL workflow confirmation, cleanup rules, and output inventory are defined in
protocols/runtime.md.
vibe is the only public wrapper entry. Installed-copy updates use the command path described above.
Compatibility stage wrappers stay internal-only. If an old caller still sends
one, collapse it to canonical vibe before runtime launch and keep it out of
the host-visible skill surface.
Skill Execution
The frozen agent_skill_organization is the only task-skill truth. Before plan
approval, disclose modules, candidates, selected skills and reasons, gaps, and the L / XL difference.
Organize each confirmed module as a verifiable work unit. Use declared Skill
outputs to identify ownership, plan_hints to shape the work steps, and
verify_hints to extend the module checks. Preserve explicit module
dependencies and keep agent_direct as the visible fallback for a module with
no suitable Skill. Every work unit must retain its intended outputs, checks,
binding reason, and dependency links in the existing WorkPlan. Each bound
assignment must project those fields and the selected Skill guidance into the
existing ModuleAssignments artifact.
Only selected skills become module-bound execution units. The host must not
invent skills, promote route candidates, hide skill sessions, or open another
requirement/plan/runtime surface. Selection, loading, planning, dispatch, or a
generic manifest is not contribution proof; completion requires observable
module results and the module acceptance defined in protocols/runtime.md.
After plan approval, module-work-plan.json is the only dispatch authority.
agent-execution-handoff.json.result_contract freezes the module_execution_v1 submission bindings; after handoff, copy result_contract.submission_template, preserve every frozen binding, and fill only the result fields. criterion_results states must be exactly passing, failing, or blocked. If canonical rejects the format before cleanup, correct the same module-execution.json and reuse the same return command instead of creating another handoff. Code-task TDD evidence belongs inside the same module-execution.json when the handoff template includes tdd_evidence; fill that structured section before canonical return and do not create a separate tdd-evidence.json sidecar. The contract is not execution evidence.
The Agent still does the real work and creates module-execution.json; required failure, blocking,
missing evidence, or pending human review blocks task completion.
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.
- Treat scaffold or draft artifacts as
needs_execution with proof_ready = false; do not call them completed work.
- Reuse completed work only while effective task inputs, selected Skill content, dependency outputs, and delivered artifact hashes remain unchanged. Rerun affected dependency chains before verification; block dependents when prerequisites fail.
- Do not use fallback or boundary behavior to bypass real execution,
verification, or root-cause repair.
- When a check fails within the confirmed scope, make at most one targeted
repair for that failure and rerun the affected check. Report the remaining
blocker when the repair fails, needs a scope decision, or lacks required
evidence.
User Delivery
Use the existing WorkDossier as the detailed evidence source. Give the user a
short delivery summary containing the verified results, their locations, the
checks that actually ran, and genuine blockers. Exclude scaffolds from
completed results. Keep internal receipts and
diagnostic detail in the dossier unless they help the user make a decision.
Protocol Map
Read these references only after canonical launch or when maintaining the repo:
protocols/runtime.md: governed runtime contract and stage ownershipprotocols/think.md: planning, research, and pre-execution analysisprotocols/do.md: coding, debugging, and verificationprotocols/review.md: review and quality gatesprotocols/team.md: XL multi-agent orchestrationprotocols/retro.md: retrospective and evidence-backed corrections
Maintenance
- Runtime family: governed-runtime-first
- Version: 4.1.1
- Updated: 2026-10-18
- Primary contract metadata:
core/skill-contracts/v1/vibe.json