Data Access Patterns

IMPORTANT: Placeholder Notation

This document uses placeholder syntax to indicate values that must be substituted from your agent prompt:

• {SCRIPTS_PATH} - Replace with the actual SCRIPTS_PATH value from your prompt
• ${CLAUDE_SESSION_ID} - Replace with the actual session ID from your prompt

These are NOT bash environment variables. They are text placeholders documenting what values you should use.

Example:

• Documentation shows: bun "{SCRIPTS_PATH}/task-get.js" --session ${CLAUDE_SESSION_ID}
• Your prompt provides: SCRIPTS_PATH: /Users/name/.claude/plugins/.../scripts and CLAUDE_SESSION_ID: abc-123
• You should execute: bun "/Users/name/.claude/plugins/.../scripts/task-get.js" --session abc-123

Core Rule: JSON via Scripts, Markdown via Read

Always use scripts for JSON data. Never use Read tool directly on JSON files.

Data Type	Access Method	Tool
session.json	session-get.js	Bash
context.json	context-get.js	Bash
tasks/*.json	task-get.js, task-list.js	Bash
exploration/*.md	Direct file read	Read
docs/plans/*.md	Direct file read	Read

Why Scripts for JSON?

1. Token Efficiency

JSON structure wastes significant context tokens:

{
  "version": "6.1",
  "session_id": "abc-123",
  "working_dir": "/path/to/project",
  "phase": "PLANNING",
  "exploration_stage": "overview",
  ...
}

Every brace, quote, comma, and key name consumes tokens. For large session files with evidence arrays, this can waste thousands of tokens.

Script output with --field flag:

bun "{SCRIPTS_PATH}/session-get.js" --session ${CLAUDE_SESSION_ID} --field phase
# Output: PLANNING

Returns only the value you need—no JSON structure overhead.

2. Field Extraction

Scripts support precise data extraction:

# Single field
bun "{SCRIPTS_PATH}/session-get.js" --session ${CLAUDE_SESSION_ID} --field phase

# Nested field (dot notation)
bun "{SCRIPTS_PATH}/session-field.js" --session ${CLAUDE_SESSION_ID} --field options.auto_mode

# AI-friendly summary
bun "{SCRIPTS_PATH}/context-get.js" --session ${CLAUDE_SESSION_ID} --summary

Benefits:

• Extract only needed data
• Support for nested field access
• Generate AI-optimized markdown summaries

3. Error Handling

Scripts provide consistent validation:

# Missing session
bun "{SCRIPTS_PATH}/session-get.js" --session invalid-id
# Error: Session not found: invalid-id

# Missing field
bun "{SCRIPTS_PATH}/task-get.js" --session ${CLAUDE_SESSION_ID} --id 999
# Error: Task not found: 999

Direct JSON reads require manual error handling for:

• File not found
• Invalid JSON
• Missing fields
• Type validation

4. Storage Format Abstraction

Scripts insulate agents from storage changes:

• File location moves
• Schema version updates
• Field renames
• Structure refactoring

Agents continue working with the same script interface.

5. Compression for AI

Scripts generate AI-friendly formats:

# Task summary (markdown, not JSON)
bun "{SCRIPTS_PATH}/task-summary.js" --session ${CLAUDE_SESSION_ID} --task 1

# Evidence index (structured for comprehension)
bun "{SCRIPTS_PATH}/evidence-summary.js" --session ${CLAUDE_SESSION_ID}

These formats optimize for AI understanding, not data transfer.

Common Access Patterns

Pattern 1: Check Current Phase

# Get phase to determine allowed operations
PHASE=$(bun "{SCRIPTS_PATH}/session-get.js" --session ${CLAUDE_SESSION_ID} --field phase)

if [ "$PHASE" = "PLANNING" ]; then
  echo "Design phase: no code edits allowed"
fi

Pattern 2: List Open Tasks

# Get tasks needing work
bun "{SCRIPTS_PATH}/task-list.js" --session ${CLAUDE_SESSION_ID} \
  --status open \
  --format json

Pattern 3: Read Task Details

# Get full task data
bun "{SCRIPTS_PATH}/task-get.js" --session ${CLAUDE_SESSION_ID} --id 1

# Get specific field
bun "{SCRIPTS_PATH}/task-get.js" --session ${CLAUDE_SESSION_ID} --id 1 --field status

Pattern 4: Update Task with Evidence

# Add evidence to task
bun "{SCRIPTS_PATH}/task-update.js" --session ${CLAUDE_SESSION_ID} --id 1 \
  --add-evidence "npm test: 15/15 passed, exit 0"

# Mark task complete
bun "{SCRIPTS_PATH}/task-update.js" --session ${CLAUDE_SESSION_ID} --id 1 \
  --status resolved \
  --add-evidence "All criteria met"

Pattern 5: Read Exploration Context

# Get AI-friendly context summary
bun "{SCRIPTS_PATH}/context-get.js" --session ${CLAUDE_SESSION_ID} --summary

# Get specific field
bun "{SCRIPTS_PATH}/context-get.js" --session ${CLAUDE_SESSION_ID} --field key_files

Pattern 6: Read Exploration Details (Markdown)

# Markdown files can be read directly
SESSION_DIR=~/.claude/ultrawork/sessions/${CLAUDE_SESSION_ID}

Then use Read tool:

Read("$SESSION_DIR/exploration/overview.md")
Read("$SESSION_DIR/docs/plans/design.md")

Pattern 7: Get Session Directory Path

# Session directory (use direct path, not a script)
SESSION_DIR=~/.claude/ultrawork/sessions/${CLAUDE_SESSION_ID}

# Then access files directly
ls "$SESSION_DIR/tasks/"
cat "$SESSION_DIR/exploration/overview.md"

Pattern 8: Query Evidence Log

# Get recent test results
bun "{SCRIPTS_PATH}/evidence-query.js" --session ${CLAUDE_SESSION_ID} \
  --type test_result \
  --last 5

# Search evidence
bun "{SCRIPTS_PATH}/evidence-query.js" --session ${CLAUDE_SESSION_ID} \
  --search "npm test"

# Get evidence for specific task
bun "{SCRIPTS_PATH}/evidence-query.js" --session ${CLAUDE_SESSION_ID} \
  --task 1

Anti-Patterns (DO NOT USE)

❌ Direct JSON Read

# WRONG: Wastes tokens, requires manual parsing
Read("~/.claude/ultrawork/sessions/${CLAUDE_SESSION_ID}/session.json")

❌ Manual JSON Parsing

# WRONG: Fragile, verbose, error-prone
cat session.json | grep '"phase"' | cut -d'"' -f4

❌ Hardcoded Paths

# WRONG: Breaks when paths change
cat ~/.claude/ultrawork/sessions/abc-123/tasks/1.json

Use scripts with ${CLAUDE_SESSION_ID} instead.

Quick Reference

Need	Script	Example
Session phase	session-get.js	--field phase
Session directory	Direct path	SESSION_DIR=~/.claude/ultrawork/sessions/${CLAUDE_SESSION_ID}
Task details	task-get.js	--id 1
Task status	task-get.js	--id 1 --field status
Open tasks	task-list.js	--status open
Context summary	context-get.js	--summary
Exploration docs	Read tool	Read("$SESSION_DIR/exploration/overview.md")
Evidence query	evidence-query.js	--type test_result --last 5
Add evidence	task-update.js	--id 1 --add-evidence "..."

Token Savings Example

Direct JSON read of session.json (~500 lines):

• Tokens: ~3000 (includes all structure, unused fields)

Script with --field phase:

• Tokens: ~5 (just the value "PLANNING")

Savings: 99.8% token reduction for single field access.

For multiple field lookups across session lifecycle, scripts save tens of thousands of tokens in main context.