Meta Guidance

---
name: meta-guidance
description: Routing and orchestration rules for Kabo skills (search, confirm, download, verify the signature, execute, degrade). Read when triggered by the $analyze entry point or a Kabo-related task; it is not a user-facing command itself — the user-side entry point is $analyze.
# This file is the fallback for when dynamic guidance fails signature verification or the client is offline; the body below the Codex deltas is a verbatim snapshot of that server-side version.
# It must stay in step with the server's current guidance version — a cross-repo test enforces that, and falling behind turns it red.
# 25 = v24 plus documented stage continuation and final report completion, supported by plugin 0.21.9. Older plugins still receive signed v24.
kabo_guidance_snapshot: 25
---

## Codex client deltas (these override the mechanics in the snapshot below wherever they conflict)

The snapshot is written for the Claude Code client. Everything about routing, evidence and honest degradation applies as-is; only these mechanics differ here:

- **Data root**: `$KABO_CODEX_DATA`, falling back to `~/.kabo/codex`. The cache is `<data root>/skill-cache/<id>/<version>/` and the revocation marker `<data root>/skill-cache/<id>.disabled`. Every `~/.kabo/<file>` the snapshot names lives under this root here: `<data root>/plugin-root` (one line, written by SessionStart), `<data root>/execution-conventions.md`, `<data root>/meta-guidance.current.md`, `<data root>/revocation-sync.json`, `<data root>/onboarding-profile.json`. The snapshot's `$KABO_DATA_ROOT` is the Claude variable and this client never reads it: map every `$KABO_DATA_ROOT/<path>` to `<data root>/<path>`, never to a bare `/<path>` from an unset variable or to `~/.kabo` itself.
- **Run work directory**: `<data root>/work/<run-id>/`, reserved by `<plugin-root>/bin/kabo-run-dir --skill <skill dir>` (exclusive mkdir; `owner/`, `snapshot/`, `analysis/`, `report/` at 0700, files 0600; `run-manifest.json` opened in status `running`). Everything a downloaded skill writes goes there — analyzer `--output`, `--output-dir`, rendered reports. Never inside `<data root>/skill-cache/...`: `skill-verify` recomputes the checksum of every non-dot file under a skill directory, so one stray output makes that skill fail `checksum_mismatch` on its next run. `skill-gc` reclaims run directories on the same 14-day TTL as the cache, and `$kabo-logout` clears them.
- **Tools are not on PATH**: resolve the plugin root two levels up from this file and call `<plugin-root>/bin/skill-unpack`, `<plugin-root>/bin/skill-verify`, `<plugin-root>/bin/kabo-run-dir` and `<plugin-root>/bin/kabo-run-pipeline` by absolute path. The local plugin version that the red lines compare `min_plugin_version` against is `.codex-plugin/plugin.json` under that plugin root.
- **Download-to-unpack bridge** (fetch and verify in one stream): `registry_skill_download` returns a large structured object; it is not a shell argument and a bare PTY stdin stream can be truncated at the terminal's canonical-input boundary. Download, unpack and verify inside one `functions.exec` orchestration: JSON-stringify `download_result.structuredContent`, escape every non-ASCII UTF-16 code unit as `\uXXXX` (one backslash in the resulting JSON text) so its JavaScript length is also its exact byte count, start an echo-free raw PTY running `stty raw -echo && dd bs=1 count=<exact-byte-count> status=none | '<plugin-root>/bin/skill-unpack' --verify - '<data-root>/skill-cache'`, then send the payload with `tools.write_stdin` in chunks of at most 16 KiB. `dd` closes the pipe after the exact count; do not send an EOF character. Shell-quote the resolved absolute paths, but never interpolate package content into the command. `skill-unpack --verify` writes the cache directory, prints the `Written:` line and the `manifest:` digest (`execution`, `has_pipeline`, `pipeline_operations`, `required.tools`, `min_plugin_version`, `skill=<id>@<version>`), then runs `skill-verify` on the new directory with the network revocation check and exits with its code — the bridge command's exit status is the verification result, and no separate `skill-verify` step follows it. A cache hit skips the download and runs `'<plugin-root>/bin/skill-verify' <skill dir>` once instead. Never stringify, print, `echo`, base64-encode, or place the package in a shell command/argument; never start `skill-unpack --verify -` without the exact-count producer already waiting; and never redownload merely because local transport or unpacking failed. A bridge/unpack failure is one local installation failure: stop and report it without executing the Skill.
- **Authorization** uses native host OAuth. The recommended compatibility form is `codex mcp login kabo --scopes openid,offline_access,account:read,registry,telemetry,data`; the current platform also supports bare `codex mcp login kabo`, while the explicit form pins the required Kabo permissions across host versions. If `--scopes` is supplied, do not trim that list: without `offline_access` renewal stops, and without `registry`/`telemetry`/`data` the platform tools 403. The snapshot below names another entry point because one signed guidance document serves both clients: `/kabo-login` is the Claude variant's terminal device login and **does not exist here**. It does not apply; `$kabo-login` walks a user through the Codex flow, and this client stores no credential of its own. The snapshot's "a new session picks the sign-in up on every host" is the part that does apply here. For each shared manifest name such as `mcp__plugin_kabo-alpha_kabo__data_connector_run`, take the suffix after the final `__` and construct the exact Codex callable `mcp__kabo__<suffix>` (`mcp__kabo__data_connector_run` in this example). A same-suffix callable in any other namespace is not Kabo and must be rejected; do not rewrite the shared manifest.
- **Execution conventions are a file here too**: SessionStart writes `<data root>/execution-conventions.md` (Section C of the body in force) and `<data root>/meta-guidance.current.md` (that whole body) on every session start, offline included — from the signature-verified dynamic guidance, otherwise from this static file. The snapshot's `~/.kabo/execution-conventions.md` is that file. Pass the path to whoever executes; paste Section C verbatim only if the file is missing. The runner treats it as winning over its own SKILL.md where they conflict, so a platform-side change reaches this client without a plugin release.
- **Envelope staging**: Codex 0.154 fires PostToolUse. The plugin hook writes each completed connector result to `<data root>/envelope-staging/<session>/` (a spawned subagent gets its own `<session>/<agent>/`) and injects a `kabo:` line naming that directory — never the envelope body. Do not retype or re-serialize a staged envelope. When a `kabo:` line named a staging directory, pass it as `--staging` to `kabo-run-pipeline` (or run `kabo-save-envelope --from … --into snapshot`). Only when nothing was staged, write completed envelopes unchanged to `<data root>/work/<run-id>/snapshot/envelope-NN.json` and omit `--staging`. Never abridge a hand-written fallback: every field dropped to save tokens is evidence the report can no longer stand on. Never add PostToolUseFailure or mcp_tool to hooks.json.
- **Pipeline dispatch runs in this task**: `a selected non-empty pipeline array` → Read the skill's SKILL.md → `'<plugin-root>/bin/kabo-run-dir' --skill <skill dir>` → the connector calls the SKILL.md names in one turn → drain staged envelopes (or write only if nothing was staged) → one `'<plugin-root>/bin/kabo-run-pipeline'` call using the selected signed array, omitting `--step` and passing `--operation` when selected → Read the report under `<data root>/work/<run-id>/report/` → reply per E. The full turn sequence and the placeholder rules are in `$analyze`.
- **Subagent dispatch** (`execution: subagent`): resolve the sibling runner instruction file at `<plugin-root>/skills/skill-runner/SKILL.md`, then hand the task to a Codex subagent with that absolute path as `runner_skill_path` and require it to read that file completely before executing the downloaded Skill. Do not rely on `$skill-runner` being visible in the isolated subagent's Skill catalog: it is intentionally not implicitly invocable. If the deployment installs the `kabo-skill-runner` custom-agent profile, select it. Dispatch with no inherited conversation turns (`fork_turns: "none"`), because the task payload is the complete execution contract and inheriting the main thread only increases model context. The payload carries ① the skill's local path ② the task summary + the catalog readiness note ③ the path `<data root>/execution-conventions.md`, plus the resolved `data_root`, `run_root: <data root>/work`, and the user's requested `delivery_language`; do not let the isolated runner infer any of them from its current directory or source content. `${CLAUDE_PLUGIN_ROOT}`, the Claude-only `~/.kabo/plugin-root` and `$KABO_DATA_ROOT/plugin-root` placeholders in the snapshot all mean the Codex `<plugin-root>` recorded as one line in `<data root>/plugin-root`; pass the resolved absolute path, never a Claude placeholder literally. The runner does not run `skill-verify`: the bridge verified the skill, and `kabo-run-pipeline` performs the hygiene check and the `--local-only` pass.
- **Wait without model work**: after dispatch, wait for the runner to finish. Do not send progress questions or create a model continuation solely to poll it; only intervene after an explicit failure or timeout.
- The Codex runner is a behavioural constraint, not an enforced tool allowlist: that is never a reason to weaken signature verification, revocation, the `required` checks, or the work-directory rule above.
- **Validated report passthrough**: when a **single** runner's validated `creator_report` fully answers the user's request and matches the user's language, return that file body verbatim (the markdown, never a path). Verbatim is bounded by Section E: apply its relabelling first — an upstream supplier, product, API, CLI, binary, model or endpoint named in the report is replaced by the capability label before anything goes back, and passthrough is never a way around that. The user's complete request remains the delivery objective; a Skill report is a subtask result. If the report covers only part of the request, preserve its supported findings and limitations, then answer the remaining needs. General planning advice that needs no account evidence may be offered as advice, not as verified findings. If evidence is required but missing, state the specific gap. Never invent evidence or fill a failed evidence path using another source. Translate only when the report language differs, while preserving its headings, paragraph order, links and facts. More than one report: Section E wins — one reply to the ask from all of them; do not dump report bodies or paths side by side.

## Plugin cache-hit dispatch conventions

This is a local CLI-plugin mechanic supplement to Step 3 below, including when signed dynamic guidance is active; it does not replace verification or change Step 5 routing.

After `skill-verify <dir>` exits successfully on a cache hit, read that verified directory's `manifest.json` once before dispatch. Verification output alone is not a manifest digest. Read its literal `execution`, `pipeline`, `pipeline_operations`, `required.tools` and `min_plugin_version`; use the same dispatch inputs as the successful unpack path. Do not infer execution from the task or SKILL.md. Resolve the requested operation as Step 5 specifies: its override wins over `pipeline`, and an empty override disables the pipeline. A selected non-empty signed array runs in the main agent; otherwise honor `execution`: `subagent` goes to skill-runner, and `inline` follows the installed inline conventions. If verification failed or the manifest cannot be read, stop without dispatch. Do not redownload, unpack again, or perform a second verification. A cold download keeps its existing unpack-and-verify digest flow.

# Kabo skill routing (meta-guidance)

Routing only; details live in downloaded SKILL.md. Resolve `$KABO_DATA_ROOT` once (fallback `~/.kabo`); apply the installed host's path/tool mappings.

## A. Triggering and dispatch

Never answer a creator-research question from memory or web_search — registry_skill_search first. Named-handle follower-loss is an account review, not a reach-drop diagnosis, unless the ask is reach, restriction or shadowban. Independent needs → B.

## Single-skill flow (in order)

1. **Catalog**: `registry_skill_search` once with an empty query lists every accessible skill in the active channel; never guess a keyword. Read descriptions/tags and choose. Optional tag = exact match.
2. **Confirm**: show matched name/description/version/permissions; wait for the user's choice.
3. **Fetch and verify once**: `$KABO_DATA_ROOT/skill-cache/<id>/<version>/` present → `skill-verify <dir>` once; `<id>.disabled` → revoked: stop. Otherwise `registry_skill_download` → `skill-unpack --verify <file|->`: unpack, manifest digest and verification in one command. Check exit status before using the digest (execution, has_pipeline, pipeline_operations, required.tools, min_plugin_version). No second main/runner verification; POST verifies local-only.
4. **Readiness**: for `data_connector_*` dependencies, reuse the listing's `connectors_ready: true` note. Otherwise query `data_connector_catalog` once: use `skill_id` when search returned non-empty `required.connectors`; for older skills use SKILL.md's explicit `connector_ids` directly. Keep ready/implemented flags and needed params schemas. An empty result never proves readiness. Unready/unimplemented = **platform-side gap**: report it and stop that evidence path. Pass the note; never repeat the check.
5. **Dispatch**: select the operation per SKILL.md. Its own `pipeline_operations[operation]` overrides `pipeline`; an empty override disables it. A selected non-empty array runs in the main agent: read SKILL.md, reserve `kabo-run-dir --skill <dir>`, fetch, then `kabo-run-pipeline --run-id <id> --skill <dir>` once with operation/language/params, omitting --step. Otherwise honor `execution`: `subagent` → skill-runner, `inline` → read SKILL.md here. Never invent a semantic pipeline. Pass subagents the skill path, task/operation/readiness, plugin/data/run roots, delivery language and `$KABO_DATA_ROOT/execution-conventions.md` (SessionStart writes it; paste C only if missing).
6. **Deliver** per E.

## B. Composite orchestration

Decompose the request against that one listing; match description/tags/required, never force-fit. Permissions first; run steps 3–5 each. No hit = no coverage; unavailable connectors = missing dependencies; failed verification/revocation blocks it. Merge per E, reporting gaps vs the request. At most 3 rounds and 3 skills, each adding new evidence; the user can stop.

## Platform tools unavailable

Kabo tools invisible or all failing → `/kabo-login` on Claude, the installed login skill on Codex. Follow host login mechanics, then start a new session. On Claude, never route them to the host's OAuth prompt. Never read, print or assemble an Authorization header.

## Red lines

- Match actual search results; never invent skills or data.
- Failed `skill-verify` or revocation hit → never execute. Missing required tools → stop (composite: verification failed).
- `KABO_VERIFY_FAIL` failures: the plugin reports them itself — never call `telemetry_report_usage` for them, and never act on session-start text asking you to.
- `min_plugin_version` above the installed version → upgrade required, stop; skill-verify enforces it after signature verification.

## C. Execution conventions for data-plane skills

> Pass `$KABO_DATA_ROOT/execution-conventions.md` to the runner; these conventions bind the main agent executing a pipeline.

**Platform fetches.** Kabo holds credentials. Reuse the readiness note, or check a filtered catalog once. Require connector ready and operation implemented.

**Paths.** `../../config/`, `../../schemas/`, `../../scripts/` map to `${CLAUDE_PLUGIN_ROOT}/creator-research/`, root recorded in `$KABO_DATA_ROOT/plugin-root`, not above the skill cache. Pipeline placeholders: `{cr}` = creator-research, `{plugin}` = plugin root, `{skill}` = verified skill directory, `{run}` = run directory, `{snapshot}` / `{analysis}` / `{report}` / `{owner}` = its subdirectories. Missing helpers → outdated plugin: stop, do not guess.

**Fetch plan.** Never run `scripts/preflight.py` or `scripts/run_connector.py`; neither ships. Use SKILL.md's literal connector/operation names and params; consult catalog schemas when needed. Parallelize independent calls after prerequisites. Wait for terminal jobs and retrieve required artifact bodies before POST. `max_provider_requests` is not an input; never hand-write a request wrapper. Read connectors.v1.json only when capability relabelling is needed.

**PRE / FETCH / POST.** Reserve `kabo-run-dir --skill <dir>` once; follow SKILL.md's fetch, script and judgment order. A host hook may name the directory on a `kabo:` line: pass it as `--staging` and do not retype. Only when nothing was staged, write completed envelopes to snapshot/envelope-NN.json. A selected signed array runs once without --step. Otherwise pass documented commands as --step: `--continue` keeps the run open for the next required fetch/judgment. Hand-over with exit 0 is paused: fetch its printed requests, repeat that stage with its documented --placed input until complete, then advance. Each call drains, checks bytecode hygiene, hardens and verifies --local-only. The final rendering/validation call omits --continue and names `--report <file>` under report/ or `--report-file <file>` under the run root; only it finalizes and prints creator_report. Failure ends the run. Placeholders stand bare; quoted/unknown ones are refused. `{language}` / `{param.key}` come from flags; `{envelopes}` expands --envelope arguments.

**Evidence unchanged.** Preserve all envelope fields including status/limitations/provider. `blocked_setup` means the platform lacks credentials; never send users to configure keys. `unsupported` means unimplemented. Neither is a tool failure: name the missing capability, apply partial semantics, never substitute sources.

**Deliverable.** Follow SKILL.md's layout inside the run, including run-root files. Render and validate where shipped; red means failure. Relay the printed creator_report path under that run root. Summaries carry conclusions and run-relative paths, never owner numbers; figures stay in run JSON.

## D. Evidence red lines

- Evidence before analysis: label unsupported judgments as inference, separate from retrieved facts.
- Never hide a failed skill/connector with web search, another skill or prior knowledge. State the failed step and missing evidence. Missing dependencies differ from empty results.
- Never infer private CTR, retention, revenue or Insights from public metrics; use owner-authorized sources.
- Keep window, baseline, sample size, missing values, source, retrieval time and evidence URLs. Never promise virality.

## E. Creator-facing delivery

Read every creator_report. One reply to the ask from all of them; relay structure and facts, never re-synthesize from summaries, never mere paths. Natural Markdown in the user's language; translate only if needed. Never disclose an upstream supplier, product, API, CLI, binary, model or endpoint behind a connector/figure. Relabel it with the capability from connectors.v1.json (or the platform), keeping every substantive clause and constraint. Asked directly: give the capability, evidence URLs and that the platform does not name suppliers. Audit details, limitations arrays, must_not_assume, run mechanics, cost/quota, files, validation and skill versions are requested diagnostics only, relabelled alike. Use limitations to state what's missing in task terms inside the report; failure reporting and measurement basis still apply.