BAZINGA-DB Core Skill

You are the bazinga-db-core skill. You manage session lifecycle, state snapshots, and system-level database operations.

When to Invoke This Skill

Invoke when:

• Creating or retrieving orchestration sessions
• Saving/restoring orchestrator or PM state
• Getting dashboard snapshots for status reporting
• Running custom SELECT queries
• Checking database integrity or recovering

Do NOT invoke when:

• Managing task groups or plans → Use bazinga-db-workflow
• Logging interactions or reasoning → Use bazinga-db-agents
• Managing context packages → Use bazinga-db-context

Script Location

Path: .claude/skills/bazinga-db/scripts/bazinga_db.py

All commands use this script with --quiet flag:

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet <command> [args...]

Commands

create-session

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet create-session \
  "<session_id>" "<mode>" "<user_request>"

Creates a new orchestration session.

Parameters:

• session_id: Unique identifier (e.g., bazinga_abc123)
• mode: simple or parallel
• user_request: Original user request text

Returns: {"session_id": "...", "status": "active", "mode": "..."}

get-session

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet get-session "<session_id>"

Returns: Full session object with all fields.

list-sessions

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet list-sessions [limit]

Parameters:

• limit: Optional, defaults to 10

Returns: Array of recent sessions ordered by created_at DESC.

update-session-status

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet update-session-status \
  "<session_id>" "<status>"

Valid status values: active, paused, completed, failed, cancelled

save-state

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet save-state \
  "<session_id>" "<state_type>" '<json_state>' [--group-id <id>]

Saves state snapshot with UPSERT semantics (insert or update).

Parameters:

• session_id: Session identifier
• state_type: orchestrator, pm, group_status, or investigation
• json_state: JSON object with state data
• --group-id: Optional group isolation key (default: global)
  • Use global for session-level state (orchestrator, pm)
  • Use task group ID for group-specific state (investigation)

Example with group_id:

python3 .../bazinga_db.py --quiet save-state \
  "bazinga_abc123" "investigation" '{"status": "in_progress"}' --group-id "CALC"

Note: Uses UPSERT - safe to call multiple times for same (session_id, state_type, group_id).

get-state

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet get-state \
  "<session_id>" "<state_type>" [--group-id <id>]

Parameters:

• --group-id: Optional group isolation key (default: global)

Returns: Latest state snapshot for the specified type and group.

dashboard-snapshot

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet dashboard-snapshot "<session_id>"

Returns: Complete dashboard data including:

• Session details
• Task groups with status
• Success criteria
• Recent orchestration logs
• Reasoning timeline

query

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet query "<sql_select>"

Execute custom SELECT query (read-only).

Example:

python3 .../bazinga_db.py --quiet query "SELECT COUNT(*) FROM sessions WHERE status='completed'"

integrity-check

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet integrity-check

Runs SQLite integrity check. Returns {"status": "ok"} or error details.

recover-db

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet recover-db

Attempts to recover corrupted database from WAL.

detect-paths

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet detect-paths

Shows auto-detected paths for database and project root.

Output Format

Return ONLY raw JSON output. No formatting, markdown, or commentary.

Error Handling

• Missing session: Returns {"error": "Session not found: <id>"}
• Invalid status: Returns {"error": "Invalid status: <status>"}
• Database locked: Retry after 100ms (automatic)

References

• Full schema: .claude/skills/bazinga-db/references/schema.md
• All commands: .claude/skills/bazinga-db/references/command_examples.md
• CLI help: python3 .../bazinga_db.py help