# 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, local-first, pulse-compatible feature cockpit.

## Current v0.1 Scope

Build only these core views:
1. Feature Plan
2. Parking Lot
3. Pulse Log
4. 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 local-first storage.
Preferred v0.1 options:
1. Browser local storage or IndexedDB for fastest implementation.
2. Optional tiny file-backed Node backend only if explicitly requested.

Do not introduce a database in v0.1.

## Scope Guardrail

When asked to add functionality, classify it first:
1. Required for v0.1
2. Useful later
3. 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:
1. Edit the single project summary.
2. Add/edit/delete/reorder feature cards.
3. Place features in Now, Next, Later, or Done.
4. Add/edit/delete Parking Lot items.
5. Add manual Pulse events.
6. Link Pulse events to features where relevant.
7. View Pulse events chronologically.
8. Export project data as JSON/JSONL.
9. Export project context as Markdown.
10. Use the exported context with Claude Code/Codex/OpenCode.