| name | handoff-packet-validator |
| description | Validates JSON handoff packets between Cinematic Studio agents including identity lock sequence extend asset manifest intimacy state and Imagine Agent Mode Handoff. Run before activating downstream agents or extend generation. Use when validating handoff.json packets or debugging chain QA failures. Uses Grok 4.5 orchestration. |
Handoff Packet Validator v3.7.1 (Grok 4.5 · Schema Gate)
Tool skill — data-driven schema checks for agent handoff JSON. Blocks broken packets before Identity Lock, extend/stitch, i2v, or Imagine spend.
Engine: .grok/skills/handoff-packet-validator/scripts/validate_handoff.py
Canonical Imagine Agent Mode schema: tools/handoff_schema.py
Field cheat sheet: references/packet_types.md
Model Layer (Grok 4.5 / v9-4p5)
| Task type | Preferred model | Reasoning |
|---|
| Critical validation (identity / spend gates) | grok-v9-4p5-chat-expert | high |
| Multi-packet / suite audits | grok-v9-4p5-multi | high |
| Routine re-checks | grok-4-auto | medium |
Registry: tools/models.py (schema 1.1+) · references/agents/MODEL_LAYER_v4.5.md · models verify
Prefer stable prompt_cache_key on multi-turn loops. Reasoning high when a failed handoff gates production spend or identity lock. Validator itself is pure Python JSON — no Imagine API spend.
When to Activate
- After
dna handoff / DNA Extractor packets
- After
sequence handoff or Sequence Extender packets
- Before
ACTIVATE IDENTITY_LOCK load of external JSON
- Before
ACTIVATE I2V_SPECIALIST or extend/stitch generation
- Before Imagine Agent Mode Handoff execution (any surface)
- When chain QA fails on continuity / momentum fields that should have been in the packet
- User says:
VALIDATE HANDOFF, RUN HANDOFF VALIDATOR, CHECK HANDOFF PACKET
When NOT Required
| Situation | Note |
|---|
| Pure in-session chat with no JSON packet | No file to validate |
| Already-locked DNA in project state without file export | Optional — re-validate if regenerating handoff.json |
| Editing prompts only | Use Imagine Prompt Master |
Supported Packet Types
packet_type | Producer → Consumer |
|---|
identity_lock_handoff | Character DNA Extractor → Identity Lock |
sequence_extend_handoff | Sequence Extender / Sequence Director → next clip / Chain QA |
asset_manifest_entry | Reference Asset Curator → i2v / batch / Prompt Master |
intimacy_state_handoff | ErosForge / NSFW Sequence Extender → next intimate clip |
imagine_agent_mode_handoff | Studio Director → Build tools / ACP / grok.com / xAI API |
Unknown packet_type → fail. See references/packet_types.md for required fields.
CLI
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py path/to/handoff.json
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py characters/hero-slug/handoff.json
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py artifacts/handoffs/clip_001_extend.json
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py packet.json --strict-handoff
| Exit | Meaning |
|---|
0 | Valid (may include ⚠️ warnings) |
1 | Schema / JSON structure errors, or readiness blockers with --strict-handoff |
2 | Usage or file not found |
Identity Continuity (drift_evidence)
For sequence_extend_handoff and identity_lock_handoff, missing or incomplete
drift_evidence produces warnings (exit 0). Invalid status enums are errors.
Protocol: references/agents/IDENTITY_CONTINUITY_PROTOCOL_v3.8.md
CLI: sequence drift-score
Generation handoff readiness (imagine_agent_mode_handoff)
After schema OK, semantic readiness runs as warnings (exit 0): empty i2v
references, video without motion cues, weak return_path, placeholder quota,
missing/incomplete specialist_checklist (GHR-09/10), etc.
Hard-fail (exit 1 on readiness blockers):
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py packet.json \
--strict-handoff
python tools/cinematic_studio_cli.py imagine agent-handoff ... --strict-handoff
Helper: tools/handoff_readiness.py · Protocol: IMAGINE_AGENT_MODE_HANDOFF_v3.7.1.md
Generate packets then validate
python tools/cinematic_studio_cli.py dna handoff "Character Name" \
--output characters/{slug}/handoff.json
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py \
characters/{slug}/handoff.json
python tools/cinematic_studio_cli.py sequence handoff "Sequence Name" --clip clip_001
python tools/cinematic_studio_cli.py imagine agent-handoff \
--batch hero-session --shot shot_hero_001 \
--surface grok_build_tools --format json \
-o artifacts/handoffs/agent_mode.json
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py \
artifacts/handoffs/agent_mode.json
Validation Engine (data-driven)
validate_packet() loads schema from PACKET_TYPES and applies:
| Rule | Behavior |
|---|
required | Field must be present |
nonempty | Non-empty string after strip |
enums | Value ∈ allowed set |
typed | list / dict / list_min / object_keys / object_any_of |
when | Conditional (e.g. video modes need video_pipeline_spec + sound_layer) |
Imagine Agent Mode field lists live in tools/handoff_schema.py (single source of truth) so validator and bridge cannot drift.
Gate Policy (Studio Director)
| Result | Action |
|---|
| Valid | Proceed to downstream agent |
| Invalid identity packet | Fix DNA / re-run dna handoff — do not lock |
| Invalid extend packet | Fix LAST_FRAME_RECAP / momentum — do not extend |
| Invalid asset entry | Curator re-tier — do not spend hero i2v |
| Invalid intimacy state | ErosForge re-state — do not NSFW-extend |
| Invalid agent-mode | Fix surface/mode/spec — block Imagine spend |
| Video mode missing sound layer | Fail — force Sound Layer block |
Never silent-pass NSFW or video handoffs with incomplete packets.
Failure Playbook
- Read printed
• issues top to bottom
- Fix producer (DNA / sequence / curator / Studio Director) — do not hand-edit casually unless user owns the packet
- Re-run generator CLI if available
- Validate again until exit 0
- Only then activate consumer agent
Output Format
HANDOFF VALIDATION · v3.7.1
File: <path>
packet_type: <type|unknown>
Result: PASS | FAIL
Issues:
- <…>
Next: <activate consumer | fix producer | block spend>
Integration
| Partner | Relationship |
|---|
| Character DNA Extractor | Emits identity_lock_handoff |
| Identity Lock Specialist | Consumes only after PASS |
| Sequence Director / Extender | Emit/consume sequence_extend_handoff |
| Chain QA Protocol | Continuity fields should match packet |
| Reference Asset Curator | asset_manifest_entry |
| Image-to-Video Specialist | Prefer locked approved assets |
| ErosForge / NSFW Sequence Extender | intimacy_state_handoff |
| Studio Director | Owns imagine_agent_mode_handoff gates |
| Imagine Execution Bridge | Classic grok.com packets (related) |
| Quality Assurance Guardian | Invalid handoff = stop before client |
Protocol Doc
Imagine Agent Mode (surfaces, modes, required fields):
references/agents/IMAGINE_AGENT_MODE_HANDOFF_v3.7.1.md
Reasoning (Grok 4.5)
| Task | Reasoning |
|---|
| Routine re-check | medium |
| Spend/identity-gating failure | high |
Handoff Packet Validator v3.7.1 — Grok 4.5 schema gate · data-driven PACKET_TYPES · block broken handoffs before spend
