buildpulse/docs/DATA_SCHEMA.md

BuildPulse Data Schema

Schema Version

Current schema version:

0.1.0

App State

{
  "schema_version": "0.1.0",
  "project": {},
  "features": [],
  "parking_lot": [],
  "pulses": [],
  "settings": {}
}

Project

{
  "id": "project_buildpulse",
  "name": "BuildPulse",
  "one_line_pitch": "A calm planning cockpit for AI-assisted product building.",
  "description": "BuildPulse helps capture features, park distracting ideas, log progress as Pulse events, and export clean context for AI coding agents.",
  "current_goal": "Ship v0.1 with Feature Plan, Parking Lot, Pulse Log, and Export.",
  "notes": "",
  "created_at": "2026-05-06T00:00:00+02:00",
  "updated_at": "2026-05-06T00:00:00+02:00"
}

Feature

{
  "id": "feature_plan_screen",
  "title": "Feature Plan screen",
  "description": "Create and manage feature cards in Now, Next, Later, and Done.",
  "column": "now",
  "priority": "must",
  "status": "ready",
  "acceptance_criteria": [
    "User can create a feature card.",
    "User can edit feature title and description.",
    "User can move feature between columns."
  ],
  "scope_notes": "No phases or releases in v0.1.",
  "created_at": "2026-05-06T00:00:00+02:00",
  "updated_at": "2026-05-06T00:00:00+02:00"
}

Feature Columns

Allowed column values:

• now
• next
• later
• done

Feature Priority

Allowed priority values:

• must
• should
• could
• later

Feature Status

Allowed status values:

• idea
• shaping
• ready
• building
• testing
• done
• parked
• rejected

In v0.1, column is more important than status.

Parking Lot Item

{
  "id": "parked_ai_triage",
  "title": "AI idea triage",
  "description": "Use AI to classify new ideas into Now, Next, Later, Parking Lot, or Reject.",
  "reason_parked": "Useful, but v0.1 must prove the manual workflow first.",
  "possible_future_placement": "v0.2",
  "risk_level": "medium",
  "created_at": "2026-05-06T00:00:00+02:00",
  "updated_at": "2026-05-06T00:00:00+02:00"
}

Parking Lot Risk Level

Allowed risk_level values:

• low
• medium
• high
• dangerous

Pulse Event

Pulse events are append-friendly and future-compatible with Agent Pulse. In v0.1, Pulse events are intentionally simple and human-readable.

{
  "id": "pulse_001",
  "timestamp": "2026-05-06T00:00:00+02:00",
  "project_id": "project_buildpulse",
  "feature_id": "feature_plan_screen",
  "source": "manual",
  "agent_id": "jimmi",
  "pulse_type": "INTENT",
  "message": "Start implementing the Feature Plan screen.",
  "confidence_score": 0.9,
  "evidence_refs": [],
  "trace_id": "session_001"
}

Pulse Types

Allowed pulse_type values:

• INTENT
• ACTION
• RESULT
• BLOCKER
• DECISION
• PARKED_IDEA
• TEST_RESULT
• SESSION_START
• SESSION_END
• REFLECTION

Pulse Source

Suggested source values:

• manual
• user
• claude_code
• codex
• opencode
• openclaw
• hermes
• local_llm
• system

v0.1 should not require strict enforcement beyond basic string handling.

Evidence Refs

Evidence refs are references to outputs, tests, commits, screenshots, files, or notes.

Simple v0.1 form:

[
  "Manual test passed",
  "Exported CLAUDE_CONTEXT.md",
  "Commit abc123"
]

Later form may become:

[
  {
    "type": "file",
    "label": "FEATURE_PLAN.md",
    "url": ""
  }
]

Future Agent Pulse Fields

The full Agent Pulse framework may later add:

• structured_payload
• event_version
• parent_event_id
• agent_capability
• tool_call_refs
• artifact_refs
• safety_classification

These are intentionally out of scope for v0.1.

Settings

Minimal v0.1 settings:

{
  "theme": "light",
  "default_agent_id": "jimmi"
}

Validation Rules

Required project fields:

• id
• name

Required feature fields:

• id
• title
• column

Required parking lot fields:

• id
• title

Required pulse fields:

• id
• timestamp
• project_id
• pulse_type
• message

Export Rule

Exports should preserve IDs exactly.

Do not regenerate IDs during export/import unless resolving duplicates is required.