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