bazinga-db-agents

name	bazinga-db-agents
description	Agent logs, reasoning, and token tracking. Use when logging interactions, saving reasoning, tracking tokens, or managing events.
version	2.0.0
allowed-tools	["Bash","Read"]

BAZINGA-DB Agents Skill

You are the bazinga-db-agents skill. You manage agent interaction logs, reasoning capture, token usage, skill outputs, and events.

When to Invoke This Skill

Invoke when:

• Logging agent interactions
• Saving or retrieving agent reasoning
• Tracking token usage
• Recording skill outputs
• Saving or querying events (TL issues, verdicts, etc.)

Do NOT invoke when:

• Managing sessions or state → Use bazinga-db-core
• Managing task groups or plans → Use bazinga-db-workflow
• 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

log-interaction

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet log-interaction \
  "<session_id>" "<agent_type>" "<message>" <sequence_num>

Logs an agent interaction in the orchestration flow.

Parameters:

• agent_type: pm, developer, sse, qa_expert, tech_lead, investigator, requirements_engineer
• sequence_num: Integer for ordering

stream-logs

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet stream-logs \
  "<session_id>" [limit] [offset]

Stream orchestration logs in markdown format. Always returns markdown (no format option).

Parameters:

• limit: Maximum number of logs to return (default: 50)
• offset: Number of logs to skip (default: 0)

save-reasoning

# Recommended: Use --content-file to avoid exposing content in process table
python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet save-reasoning \
  "<session_id>" "<group_id>" "<agent_type>" "<phase>" \
  --content-file /tmp/reasoning.txt [--confidence N] [--tokens N]

# Alternative: Inline content (avoid for sensitive data)
python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet save-reasoning \
  "<session_id>" "<group_id>" "<agent_type>" "<phase>" "<content>" \
  [--confidence N] [--tokens N]

Saves agent reasoning with automatic secret redaction.

⚠️ Security: Prefer --content-file over inline content to avoid exposing reasoning in process listings.

Phases: understanding, approach, decisions, risks, blockers, pivot, completion

Example (recommended):

# Write content to temp file first
cat > /tmp/reasoning.txt << 'EOF'
Analyzed requirements: need add/subtract/multiply/divide operations
EOF

python3 .../bazinga_db.py --quiet save-reasoning \
  "bazinga_xxx" "CALC" "developer" "understanding" \
  --content-file /tmp/reasoning.txt --confidence 85

get-reasoning

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet get-reasoning \
  "<session_id>" [group_id] [agent_type] [phase]

Retrieve reasoning entries with optional filters.

reasoning-timeline

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet reasoning-timeline \
  "<session_id>" [--group_id "<group_id>"] [--format markdown|json]

Get chronological reasoning timeline across all agents, optionally filtered by group.

Parameters:

• --group_id: Optional filter by task group (e.g., AUTH, CALC)
• --format: Output format (json default, or markdown for human-readable)

check-mandatory-phases

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet check-mandatory-phases \
  "<session_id>" "<group_id>" "<agent_type>"

Check if agent documented mandatory phases (understanding, completion).

Returns: {"complete": true/false, "missing": [...]}

log-tokens

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet log-tokens \
  "<session_id>" "<agent_type>" <token_count> [model]

Log token usage for an agent.

token-summary

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

Get token usage summary by agent and model.

save-skill-output

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet save-skill-output \
  "<session_id>" "<group_id>" "<skill_name>" '<json_output>'

Save skill execution output for audit trail.

Example:

python3 .../bazinga_db.py --quiet save-skill-output \
  "bazinga_xxx" "AUTH" "specialization-loader" \
  '{"templates_used": ["python.md"], "token_count": 450}'

get-skill-output

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet get-skill-output \
  "<session_id>" "<skill_name>" [group_id]

Get latest skill output, optionally filtered by group.

get-skill-output-all

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet get-skill-output-all \
  "<session_id>" [skill_name]

Get all skill outputs for a session.

check-skill-evidence

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet check-skill-evidence \
  "<session_id>" "<skill_name>" [--within-minutes N]

Check for recent skill invocation evidence.

save-event

# Recommended: Use --payload-file and --group-id for full isolation
python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet save-event \
  "<session_id>" "<event_subtype>" \
  --payload-file /tmp/event_payload.json \
  --idempotency-key "{session}|{group}|{type}|{iter}" \
  --group-id "<group_id>"

# Alternative: Inline JSON (avoid for sensitive or large payloads)
python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet save-event \
  "<session_id>" "<event_subtype>" '<json_payload>' \
  [--idempotency-key "<key>"] [--group-id "<id>"]

Save a generic event with JSON payload.

Options:

• --payload-file <path>: Read payload from file (recommended for security)
• --idempotency-key <key>: Prevent duplicate events with same key
• --group-id <id>: Group isolation key (default: global). Used in idempotency check.

⚠️ Security Best Practices:

1. Use --payload-file instead of inline JSON to avoid exposing data in ps aux
2. Always use --idempotency-key for consistent deduplication
3. Use --group-id for parallel mode to isolate events per task group
4. Large payloads: Must use --payload-file to avoid shell quoting issues and argv limits

Idempotency Key Format:

{session_id}|{group_id}|{event_type}|{iteration}

Example: bazinga_abc123|AUTH|tl_issues|2

Common event types:

• scope_change - User approved scope reduction
• role_violation - Detected role boundary violation
• tl_issues - Tech Lead issues after CHANGES_REQUESTED
• tl_issue_responses - Developer responses to TL issues
• tl_verdicts - TL verdicts on Developer rejections
• investigation_iteration - Investigator agent iteration progress
• pm_bazinga - PM sends BAZINGA completion signal
• validator_verdict - Validator ACCEPT/REJECT decision

Tech Lead Review Events (Recommended Pattern):

# Write payload to temp file (avoid inline JSON for security)
cat > /tmp/tl_issues.json << 'EOF'
{"group_id": "AUTH", "iteration": 1, "issues": [...], "blocking_count": 3}
EOF

# Save with idempotency and group isolation
python3 .../bazinga_db.py --quiet save-event \
  "sess_123" "tl_issues" \
  --payload-file /tmp/tl_issues.json \
  --idempotency-key "sess_123|AUTH|tl_issues|1" \
  --group-id "AUTH"

# Developer responses
cat > /tmp/dev_responses.json << 'EOF'
{"group_id": "AUTH", "iteration": 1, "issue_responses": [...]}
EOF

python3 .../bazinga_db.py --quiet save-event \
  "sess_123" "tl_issue_responses" \
  --payload-file /tmp/dev_responses.json \
  --idempotency-key "sess_123|AUTH|tl_issue_responses|1" \
  --group-id "AUTH"

Deduplication: Events are deduplicated by (session_id, event_subtype, group_id, idempotency_key). If the same idempotency key is used, the event is skipped and the existing event_id is returned.

get-events

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet get-events \
  "<session_id>" [event_subtype] [limit]

Query events by session and optionally by subtype.

save-investigation-iteration (Atomic)

python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet save-investigation-iteration \
  "<session_id>" "<group_id>" <iteration> "<status>" \
  --state-file /tmp/state.json --event-file /tmp/event.json

Atomically save investigation state AND event together. Ensures consistency between state (for resumption) and events (for audit trail). Uses single transaction.

Parameters:

• iteration: Integer iteration number (1-10)
• status: under_investigation, root_cause_found, hypothesis_eliminated, etc.
• --state-file: Path to JSON file with investigation state data
• --event-file: Path to JSON file with event payload

Returns:

{
  "success": true,
  "atomic": true,
  "state_saved": true,
  "event_saved": true,
  "event_id": 123,
  "iteration": 1,
  "idempotent": false
}

Output Format

Default: Return raw JSON output. No formatting or commentary.

Exceptions:

• reasoning-timeline with --format markdown - Returns formatted markdown timeline
• stream-logs - Always returns markdown (no JSON option)

When a command returns markdown, output it directly without wrapping in JSON.

Error Handling

• Missing session: Returns {"error": "Session not found: <id>"}
• Invalid phase: Returns {"error": "Invalid phase: <phase>"}
• JSON parse error: Returns {"error": "Invalid JSON: <details>"}

References

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