Vibe Coding Tips

I want to build an OpenHome Ability.

CONTEXT (read first):
- SDK Reference: https://docs.openhome.com/api-sdk/sdk-reference
- Cookbook: https://docs.openhome.com/building-abilities/cookbook
- Voice-First rules: https://docs.openhome.com/guides/best-practices/voice-first

THE ABILITY:
Name: Meeting Notes
Category: skill (hotword-triggered)
Trigger words: "take notes", "start meeting notes", "note this meeting"
Behavior:
  - On trigger, start recording with self.capability_worker.start_audio_recording()
  - Loop listening for "meeting finished" via user_response()
  - When finished, stop recording, get audio bytes
  - POST to Deepgram with diarize=true, utterances=true, smart_format=true
  - LLM-summarize the diarized transcript into action items + speaker summary
  - Speak a 2-sentence recap, write the full notes to a persistent file
  - resume_normal_flow() on every exit path

CONSTRAINTS:
- Follow every sandbox rule in the SDK Reference
- Use session_tasks.create(), not asyncio.create_task
- No print(), use editor_logging_handler
- Keep speak() calls to 1–2 sentences

Architect the solution first (files, loops, patterns). Then write the code.

1. Claude writes main.py
2. Claude: `openhome deploy ability .`  (CLI packages and uploads)
3. Claude: `openhome chat --agent <your agent>`  (chat with the Ability)
4. Claude reads the response, adjusts main.py, loops

Build a Flask server that receives POSTs from an external Python client
(an OpenHome ambient voice ability) and serves a polling-based dashboard.

ENDPOINTS TO ACCEPT (all JSON POST):
- POST /api/<ability>/session_start — fires once when ability starts
- POST /api/<ability>/update — fast cycle updates every 10s
  Contains: tone, scene, speaker_state, running_log, cycle_id, elapsed
- POST /api/<ability>/deep — slow cycle updates every 60s
  Contains: deep_insight, emotional_arc, notable_moments
- POST /api/<ability>/heartbeat — lightweight keepalive every 10s when idle
- POST /api/<ability>/session_end — fires once when ability stops

READ ENDPOINTS (GET, returns JSON):
- GET /api/state — returns the current consolidated state object
- GET /api/history — returns the last N cycle snapshots

STORAGE:
- In-memory Python dict. No database. Last-write-wins per session_id.
- Keep the last 100 cycle snapshots in a collections.deque.
- On cold start, state is empty; the ability will re-flood within one cycle.

FRONTEND:
- Single index.html, vanilla JS, polls /api/state every 2 seconds.
- Tabs: LIVE, TIMELINE, SPEAKERS, INSIGHTS, RAW DATA.
- Use Tailwind via CDN. Dark theme. No frameworks.
- Each tab reads from the same STATE object; no extra API calls per tab.

CORS:
- Allow all origins. The POSTs come from a sandboxed environment
  with no fixed IP address.

ROBUSTNESS:
- Every endpoint must accept unexpected fields without erroring.
- Log the full payload to console on receipt for debugging.
- Return {"ok": true} on success. Never 500 on a missing field.
- Nested dicts should merge, not overwrite; lists should replace.

Bind to host="0.0.0.0", port=8080.

Build a single index.html dashboard that polls GET /api/state every 2s
and renders the current state of an ambient voice ability.

LAYOUT:
- Fixed top header: session ID, elapsed time, connection status dot
  (green = updated in last 15s, amber = 15–60s stale, red = >60s)
- Five tabs below: LIVE, TIMELINE, SPEAKERS, INSIGHTS, RAW DATA
- Tab content fills the rest of the viewport

LIVE TAB:
- Large card showing current room energy / dominant tone
- Grid of speaker cards (one per speaker in speaker_registry)
- Each card: name/id, gender+age, current tone, energy bar, vocal quality

TIMELINE TAB:
- Vertical list of running_log entries, newest at top
- Each entry: timestamp badge, observation text
- Subtle color coding by entry type (arrival, topic shift, tone shift)

SPEAKERS TAB:
- Expanded speaker profiles with voice_signature, emotional_arc, undercurrent
- "Present" / "Left the room" badges

INSIGHTS TAB:
- The latest deep_insight payload rendered as a narrative card

RAW DATA TAB:
- Pretty-printed JSON of the full STATE object, in a scrollable pre block

STYLE:
- Tailwind via CDN. Dark theme (slate-900 background, slate-100 text).
- Accent: indigo-400. Use rounded-2xl cards with subtle ring-1 ring-slate-700.
- No frameworks. No build step. One file.

# =============================================================================
# PROMPTS
# =============================================================================

SYSTEM_PROMPT = """..."""
INTENT_PROMPT = """..."""
FAREWELL_PROMPT = """..."""

# =============================================================================
# CONSTANTS
# =============================================================================

DASHBOARD_URL = "https://..."
HEARTBEAT_INTERVAL = 10
MAX_SPEAKERS = 4

class YourCapability(MatchingCapability):
    worker: AgentWorker = None
    capability_worker: CapabilityWorker = None

    #{{register capability}}

# Good
self.worker.session_tasks.create(self.heartbeat_loop())

# Bad — blocked by sandbox
asyncio.create_task(self.heartbeat_loop())