BuildPulse — AI Agent Instructions

Product Goal

BuildPulse is an ADHD-safe planning cockpit for AI-assisted product development. It helps the user capture features, park distracting ideas, log progress as Pulse events, and export clean context for AI coding agents.

Current Release

v0.1: Single-project, Appwrite-backed, pulse-compatible feature cockpit.

Current v0.1 Scope

Build only these core views:

Feature Plan
Parking Lot
Pulse Log
Export

Hard v0.1 Constraints

Do not add:

Multiple projects
Phases
Releases
AI triage
LLM provider configuration
Local/cloud model routing
Real agent integration
WebSockets
Authentication
Database
GitHub/Gitea integration
OpenClaw integration
Multi-user support
Notification system
Advanced analytics
Mobile native app

If a useful idea appears, add it to docs/PARKING_LOT.md or the app's Parking Lot data instead of implementing it.

Core Data Concepts

BuildPulse v0.1 has:

One Project
Many Features
Many Parking Lot Items
Many Pulse Events

Sessions are not a separate entity in v0.1. Sessions are represented using Pulse events with a shared trace_id.

Pulse Types

Support at minimum:

INTENT
ACTION
RESULT
BLOCKER
DECISION
PARKED_IDEA
TEST_RESULT
SESSION_START
SESSION_END
REFLECTION

UX Principles

The UI must be:

Calm
Minimal
Clear
Mobile-friendly
Not enterprise-heavy
Not Jira-like
Easy to understand quickly
Designed for one person building with AI help

Code Principles

Prefer simple, readable code.
Prefer boring architecture.
Keep the app working after every change.
Use clear names.
Add comments where helpful.
Keep state structure close to the documented data schema.
Validate required fields.
Handle empty states.
Handle import errors gracefully.
Keep export output human-readable.

Storage Rule

Use Appwrite on the Unraid server as canonical storage. Keep a browser local cache fallback so the app still behaves when the backend sulks.

Scope Guardrail

When asked to add functionality, classify it first:

Required for v0.1
Useful later
Dangerous scope expansion

Only implement category 1 unless explicitly told otherwise.

End-of-Task Report

After every coding task, report:

What changed
What files changed
How to run/test
What remains rough
What ideas were parked
Whether v0.1 definition of done is closer

Definition of Done for v0.1

BuildPulse v0.1 is done when the user can:

Edit the single project summary.
Add/edit/delete/reorder feature cards.
Place features in Now, Next, Later, or Done.
Add/edit/delete Parking Lot items.
Add manual Pulse events.
Link Pulse events to features where relevant.
View Pulse events chronologically.
Export project data as JSON/JSONL.
Export project context as Markdown.
Use the exported context with Claude Code/Codex/OpenCode.

2.9 KiB Raw Blame History