buildpulse/docs/DECISIONS.md

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, and evidence_refs.
• Richer Agent Pulse fields such as structured_payload are intentionally parked until later versions.
• 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 — Appwrite Canonical Storage with Local Cache Fallback

Date: 2026-05-06

Decision: BuildPulse v0.1 stores canonical state in Appwrite on the Unraid server, with a local cache fallback in the browser.

Reason: This keeps the first version durable across sessions while still feeling fast and forgiving in the browser.

Consequences:

• No custom auth.
• Export/import is important to avoid lock-in.
• The browser cache is a fallback, not the source of truth.

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.