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,127 @@
+# BuildPulse Decisions
+
+## Decision 001 — BuildPulse Starts as Planning Cockpit, Not Agent Framework
+
+Date:
+2026-05-06
+
+Decision:
+BuildPulse v0.1 will be a planning cockpit, not a full Agent Pulse event framework.
+
+Reason:
+The full Agent Pulse concept is powerful but too large for v0.1. The user needs a practical planning and scope-control system first.
+
+Consequences:
+- No WebSockets.
+- No real agent ingestion.
+- No event bus.
+- Manual Pulse entries only.
+- Pulse-compatible schema from day one.
+
+## Decision 002 — Pulse-Compatible From Day One
+
+Date:
+2026-05-06
+
+Decision:
+BuildPulse v0.1 will store progress as Pulse-shaped events even when events are manually created.
+
+Reason:
+This allows future autonomous agents to emit the same event shape without a major data model rewrite.
+
+Consequences:
+- Pulse schema includes future-friendly fields such as `agent_id`, `trace_id`, `confidence_score`, `structured_payload`, and `evidence_refs`.
+- v0.1 UI may not use all fields deeply.
+
+## Decision 003 — Single Project in v0.1
+
+Date:
+2026-05-06
+
+Decision:
+BuildPulse v0.1 supports one active project only.
+
+Reason:
+Multiple projects add navigation, filtering, data complexity, and scope risk. The first version should prove the core workflow.
+
+Consequences:
+- Project data exists, but only one project is active.
+- Multi-project support is parked for later.
+
+## Decision 004 — No Phases or Releases in v0.1
+
+Date:
+2026-05-06
+
+Decision:
+Phases and releases are not part of v0.1.
+
+Reason:
+The first version only needs to manage features and parked ideas. Phases/releases become useful after the core feature cockpit works.
+
+Consequences:
+- Features are grouped by Now, Next, Later, Done.
+- Phases/releases are parked for v0.3.
+
+## Decision 005 — Sessions Are Pulse Events in v0.1
+
+Date:
+2026-05-06
+
+Decision:
+Build sessions are represented as Pulse events with shared `trace_id`.
+
+Reason:
+A separate session model adds complexity. Pulse events can already represent session starts, actions, results, and endings.
+
+Consequences:
+- Pulse types include SESSION_START and SESSION_END.
+- Session view may come later.
+- Trace IDs allow grouping session-related pulses later.
+
+## Decision 006 — Local-First Storage
+
+Date:
+2026-05-06
+
+Decision:
+BuildPulse v0.1 uses local-first storage.
+
+Reason:
+This keeps the first version simple, fast, private, and easy to run.
+
+Consequences:
+- No database.
+- No auth.
+- Export/import is important to avoid lock-in.
+
+## Decision 007 — Export Is a Core Feature
+
+Date:
+2026-05-06
+
+Decision:
+Markdown/JSON export is required in v0.1.
+
+Reason:
+BuildPulse must produce useful handoff context for AI coding agents.
+
+Consequences:
+- `CLAUDE_CONTEXT.md` is a primary output.
+- JSON and JSONL exports preserve future compatibility.
+
+## Decision 008 — Local LLM Is Not a v0.1 Blocker
+
+Date:
+2026-05-06
+
+Decision:
+Local LLMs may assist development but are not required to build or run v0.1.
+
+Reason:
+The project must not become blocked by local model setup, GPU issues, inference tooling, or model comparisons.
+
+Consequences:
+- Claude Code/Codex/cloud tools may build v0.1.
+- Local models can be tested as reviewers or for isolated tasks.
+- Local/cloud router is parked for later.