hermes-creative-telegram-review

/home/avalon/.hermes/skills/creative/hermes-creative-telegram-review/SKILL.md · raw

Hermes Creative Telegram Review

Use this skill when Alex asks to review, approve, reject, or understand Hermes Creative items from Telegram.

Purpose

Telegram should be a first-class review cockpit for Hermes Creative. The agent should show the item, explain exactly what approval will do, and accept a simple approve/reject/delete decision from Telegram without forcing Alex into the web UI.

Review object types and effects

asset / image asset
Show native Telegram media when media_url or file_path is available.
Approval means: mark the image/reference approved for the trusted media vault and future briefs/drafts.
Approval does not start an agent run.
Suggested next action after approval: offer to create a creative brief using this asset or a selected batch.
creative_brief
Show the brief goal, channel, task type, constraints, recommended assets, avoid patterns, and timestamps.
Approval means: trigger a local-only draft agent run.
Approval does not publish or spend.
creative_output
Show draft title/body, source brief id, source run id, channel, status, and timestamps.
Approval means: mark the generated draft usable for export/handoff.
Approval does not publish or schedule.
direction / brand_strategy
Show strategy/direction summary and rationale.
Approval means: save as usable brand/creative context.

Default Telegram response format

For each item, keep it compact:

Review item <id> · <Type>
Created: <date/time>
Updated: <date/time>
Source: <brief/run/asset source if known>

What this is: <one sentence>
What approval does: <one sentence>
Safety: local-only / no publish / no spend, if applicable.

<Question>
Reply: approve <id>, reject <id> <reason>, delete <id>, or more <id>.

If media exists, send it as MEDIA:/absolute/path or markdown image URL before/with the text.

Tool/API pattern

App path: /home/avalon/apps/hermes-creative Base URL: http://127.0.0.1:4030

List pending review items:

curl -fsS http://127.0.0.1:4030/api/projects/<slug>/review

Decide an item:

curl -fsS -X POST http://127.0.0.1:4030/api/review/<review_id>/decision \
  -H 'Content-Type: application/json' \
  --data '{"decision":"approved","note":"Telegram approval"}'

Delete from review:

curl -fsS -X DELETE http://127.0.0.1:4030/api/review/<review_id> \
  -H 'Content-Type: application/json' \
  --data '{"note":"Telegram delete"}'

Critical UX rules

Always state the item type before asking for approval.
Always include created/updated timestamps when available.
Always explain the effect of approval.
Never imply asset approval starts an agent run.
Never imply output approval publishes/schedules.
For images, send the image natively in Telegram, not just a link.
For video outputs, send native Telegram video media when available and include an edit/open link, not just text.
If the user approves an asset and seems to expect a run, explain that the next step is creating/approving a creative brief.
If a brief approval triggers a run, report the run id and generated output ids.

Video Story export review cards

When a Video Story export is registered as a creative_output, treat the MP4 as reviewable content:

Copy/own the final MP4 in the Hermes Creative media vault and use that path/URL for review previews.
Create a pending creative_output review row; approval means usable for downstream handoff only.
Immediately send the Telegram review card from the registration path. Do not assume a later watcher/cron will pick it up, and do not answer the user with only a manual link/file when the official approval flow is expected.
Telegram card should include native video preview plus Approve / Reject / More buttons.
Include an Edit in Video Story URL button. Prefer path-style project links (https://video-story.apps.poofc.com/project/<project_id>) over query-only links; verify the app actually opens the project, not just the homepage.
Include Video Story-specific callback buttons when the gateway supports them: vsedit:start:<review_id> for Telegram edit mode and vsedit:review:<review_id> for overlay review video assembly.
After changing any inline-button URL, send a fresh Telegram card — existing Telegram inline buttons keep their original URL.
See references/video-story-output-review-deeplinks.md, references/video-story-output-direct-telegram-send.md, and references/video-story-direct-review-card-routing.md for session-derived deep-link/direct-send/routing checklists.

If a brief approval triggers a run, report the run id and generated output ids.

Routing and direct-send pitfalls

If Alex expects a review card “here in Telegram,” treat the current chat/topic as part of the delivery requirement. A successful Telegram API response to Alex's DM or a different topic is not success.
App-originated review sends should prefer an explicit Hermes Creative delivery target (HERMES_CREATIVE_TELEGRAM_CHAT_ID plus optional HERMES_CREATIVE_TELEGRAM_THREAD_ID) or request/origin context before falling back to TELEGRAM_HOME_CHANNEL.
When debugging a missing card, check both halves separately: (1) review row creation/status, and (2) actual Telegram destination/message id. Do not describe existing gateway callbacks as “missing integration”; the more common failure is missing registration trigger or wrong destination.
For a manual test of the approve/reject buttons, choose an existing pending review item, send it to the active topic, then let Alex click the inline buttons. Do not pre-approve or reject it via API unless the user specifically asks for that.

Telegram button contract

Hermes Creative review callbacks in the Telegram gateway use compact callback data:

hc:approve:<review_id> — approve review item.
hc:reject:<review_id> — reject review item.
hc:more:<review_id> — fetch/show expanded detail.

URL-only actions such as Edit in Video Story should be regular Telegram URL buttons, not callback buttons. If adding new callback verbs such as social/ads handoff, update the gateway callback allowlist and handler before emitting them.

Future app integration target

A complete Telegram implementation should add a server-side endpoint that returns Telegram-ready review payloads, including:

review id
item type label
created/updated timestamps
title/body
approval effect copy
media file path or URL
source ids (source_brief_id, run_id, asset_id)
suggested next actions

Then a Telegram gateway/bot layer can render inline Approve / Reject / More buttons that call the review decision endpoint.

Video Story export review pattern

When a Video Story export becomes a Hermes Creative creative_output, make the Creative review item own the review lifecycle:

Register/copy the final MP4 into the Creative media vault, rather than only posting the transient Video Story upload path.
Create a pending creative_output review row with preview_kind: video / video media metadata.
Telegram review card should include native video preview, approve/reject/more callbacks, and an Edit in Video Story URL action.
Approval should mean “usable for downstream handoff” only; it must not publish, schedule, or spend.
Social/Ads handoff buttons should be approval-gated unless the user explicitly asks to bypass review. After approval, prefer a follow-up card/action row such as Create Social draft / Prepare Ads draft rather than publishing or spending directly.
The Video Story registration endpoint itself should push the Telegram review card as soon as it creates the review item; this is not a watcher-only concern.
Before adding the editor URL to Telegram, verify the target app actually honors the project deep link. A URL like https://video-story.apps.poofc.com/?project=<uuid> is only useful if the React app reads URLSearchParams, fetches /api/projects/:id, and opens the project after PIN/auth; otherwise it just lands on the homepage.

Pitfall: Telegram gateway restarts only load callback-handler code; they do not fix target-app deep links. If a URL button opens the app homepage, debug the target PWA/router/deep-link handling, not the Telegram button rendering first.