chore: seed BuildPulse v0.1 documentation package

2026-05-06 23:59:31 +02:00
commit 8f0ba43728
14 changed files with 2427 additions and 0 deletions
@@ -0,0 +1,226 @@
+# BuildPulse Data Schema
+
+## Schema Version
+
+Current schema version:
+
+```text
+0.1.0
+```
+
+## App State
+
+```json
+{
+  "schema_version": "0.1.0",
+  "project": {},
+  "features": [],
+  "parking_lot": [],
+  "pulses": [],
+  "settings": {}
+}
+```
+
+## Project
+
+```json
+{
+  "id": "project_buildpulse",
+  "name": "BuildPulse",
+  "one_line_pitch": "A local-first 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
+
+```json
+{
+  "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
+
+```json
+{
+  "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.
+
+```json
+{
+  "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.",
+  "structured_payload": {},
+  "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:
+
+```json
+[
+  "Manual test passed",
+  "Exported CLAUDE_CONTEXT.md",
+  "Commit abc123"
+]
+```
+
+Later form may become:
+
+```json
+[
+  {
+    "type": "file",
+    "label": "FEATURE_PLAN.md",
+    "url": ""
+  }
+]
+```
+
+## Settings
+
+Minimal v0.1 settings:
+
+```json
+{
+  "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.