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.

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

```powershell
$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:

```bash
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:

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.

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

```bash
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:

```json
{
  "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:

1. `skeleton_check`
2. `deep_interview`
3. `requirement_doc`
4. `xl_plan`
5. `plan_execute`
6. `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