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,158 @@
+# BuildPulse Export Formats
+
+## Export Goals
+
+Exports must support:
+1. Backup/restore
+2. AI coding agent handoff
+3. Future Agent Pulse compatibility
+4. Human-readable project review
+
+## Export Types
+
+v0.1 supports:
+- Full JSON export
+- Pulse JSONL export
+- Markdown context package
+
+## Full JSON Export
+
+File name:
+
+```text
+buildpulse-export.json
+```
+
+Shape:
+
+```json
+{
+  "schema_version": "0.1.0",
+  "exported_at": "2026-05-06T00:00:00+02:00",
+  "project": {},
+  "features": [],
+  "parking_lot": [],
+  "pulses": [],
+  "settings": {}
+}
+```
+
+## Pulse JSONL Export
+
+File name:
+
+```text
+pulses.jsonl
+```
+
+Rules:
+- One JSON object per line.
+- Each line is one Pulse event.
+- Preserve event IDs.
+- Preserve timestamps.
+- Do not wrap in an array.
+
+Example:
+
+```jsonl
+{"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 Feature Plan.","structured_payload":{},"confidence_score":0.9,"evidence_refs":[],"trace_id":"session_001"}
+{"id":"pulse_002","timestamp":"2026-05-06T00:30:00+02:00","project_id":"project_buildpulse","feature_id":"feature_plan_screen","source":"claude_code","agent_id":"claude_code","pulse_type":"RESULT","message":"Feature card creation implemented.","structured_payload":{},"confidence_score":0.8,"evidence_refs":["Manual test passed"],"trace_id":"session_001"}
+```
+
+## Markdown Package
+
+The Markdown export should generate these files:
+- `PROJECT_SUMMARY.md`
+- `FEATURE_PLAN.md`
+- `PARKING_LOT.md`
+- `PULSE_LOG.md`
+- `CLAUDE_CONTEXT.md`
+
+## PROJECT_SUMMARY.md
+
+Must include:
+- Project name
+- One-line pitch
+- Description
+- Current goal
+- Notes
+
+## FEATURE_PLAN.md
+
+Must include features grouped by:
+- Now
+- Next
+- Later
+- Done
+
+Each feature should include:
+- Title
+- Description
+- Priority
+- Acceptance criteria
+- Scope notes
+
+## PARKING_LOT.md
+
+Must include:
+- Title
+- Description
+- Reason parked
+- Possible future placement
+- Risk level
+
+## PULSE_LOG.md
+
+Must include recent Pulse events, newest first or chronological.
+
+Each pulse should include:
+- Timestamp
+- Pulse type
+- Feature
+- Source/agent
+- Message
+- Confidence
+- Evidence refs
+
+## CLAUDE_CONTEXT.md
+
+This is the most important AI handoff file.
+
+It should include:
+
+# AI Coding Context
+## Project
+<Project summary>
+## Current Goal
+<Current project goal>
+## Active Features
+<Now features>
+## Next Features
+<Next features>
+## Done Features
+<Done features>
+## Parking Lot / Do Not Implement Yet
+<Parking lot items>
+## Recent Pulse Events
+<Recent important pulses>
+## Instructions for AI Developer
+- Only work on the selected feature.
+- Do not implement Parking Lot items.
+- Preserve working behavior.
+- Report changes and test steps.
+
+## Import Rules
+
+When importing JSON:
+- Validate schema version.
+- Validate required fields.
+- Show useful error if invalid.
+- Preserve IDs.
+- Avoid silent data loss.
+- If schema version differs, warn user.
+
+## Copy-to-Clipboard
+
+If downloading multiple files is complex in v0.1, support copying each Markdown output to clipboard.
+
+Download can be added later.