Vibe

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 upgrades stay on the command path. Use the repo's update entry with --skills-dir for the same managed skills directory instead of starting a separate skill flow.

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 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

Specialist recommender input rules:

This audit runs inside canonical vibe; it may expose candidates for inspection, but it does not choose task skills, bind execution, or control stage progression.

• Include work type, domain/technology, deliverable, and explicit constraints.
• Reuse verified frozen requirement/plan facts when continuing a run.
• Treat its output as compatibility evidence only; never relabel a routed candidate as an Agent choice.

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, should avoid Bash-wrapped PowerShell. Set PYTHONPATH in the outer shell and call Python directly. If py -3 is unavailable, try python instead. If python is unavailable, try python3.

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>"

A normal launch does not need explicit --host-id or --entry-id. Those flags remain compatibility-only for wrappers or older automation that already carries them.

Only validate canonical proof artifacts after canonical-entry returns a session_root. check on an installed copy proves only installed locally. It does not prove runtime coherent or delivery accepted. 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 as a real conversation. Continue until the user and Agent share a concrete understanding of the goal, scope, constraints, deliverables, unknowns that affect the work, and completion criteria. A first clarification response is input to that conversation; freeze the requirement only when the user has confirmed the resulting task-specific summary.

Keep that agreement in the existing TaskCard. When the user changes the work, append an accepted revision, update the affected work units and checks, and reuse completed work whose inputs and acceptance criteria remain valid. Surface a new decision only when it changes the agreed outcome, scope, risk, or required human judgment.

Hard Stop And Re-entry

vibe uses progressive governed stops:

1. requirement_doc
2. xl_plan
3. 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.

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",
  "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": [
    "Freeze one public small/medium face dataset downloaded locally.",
    "Require a polished LaTeX paper and compiled PDF."
  ]
}

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.