buildpulse/docs/AI_DEVELOPER_HANDOFF.md

# AI Developer Handoff — BuildPulse v0.1

## Mission

Build a tiny local-first app called BuildPulse.
BuildPulse v0.1 is a single-project planning cockpit for AI-assisted development.
It must allow the user to:
1. Manage a simple feature plan.
2. Park distracting ideas.
3. Manually log progress as Pulse events.
4. Export clean project context for AI coding agents.

## Do Not Overbuild

This is not a full project management platform.
This is not an autonomous agent system.
This is not the full Agent Pulse framework.
Build only the v0.1 scope.

## Required Views

### 1. Feature Plan

Columns:
- Now
- Next
- Later
- Done

Feature fields:
- Title
- Description
- Column
- Priority
- Status
- Acceptance criteria
- Scope notes

Required actions:
- Add feature
- Edit feature
- Delete feature
- Move feature between columns

### 2. Parking Lot

Parking item fields:
- Title
- Description
- Reason parked
- Possible future placement
- Risk level

Required actions:
- Add item
- Edit item
- Delete item

### 3. Pulse Log

Pulse event fields:
- Timestamp
- Project ID
- Feature ID, optional
- Source
- Agent ID
- Pulse type
- Message
- Structured payload
- Confidence score
- Evidence refs
- Trace ID, optional

Pulse types:
- INTENT
- ACTION
- RESULT
- BLOCKER
- DECISION
- PARKED_IDEA
- TEST_RESULT
- SESSION_START
- SESSION_END
- REFLECTION

Required actions:
- Add pulse
- View pulses chronologically
- Link pulse to feature, optional

### 4. Export

Required exports:
- Full JSON export
- Pulse JSONL export
- Markdown package export

Markdown package:
- `PROJECT_SUMMARY.md`
- `FEATURE_PLAN.md`
- `PARKING_LOT.md`
- `PULSE_LOG.md`
- `CLAUDE_CONTEXT.md`

## Storage

Use local-first browser persistence unless explicitly told otherwise.
Preferred:
- LocalStorage or IndexedDB

Do not add:
- Database
- Auth
- Backend

## Initial Seed Data

The app may seed itself with this project:

Project name:
BuildPulse

One-line pitch:
A local-first planning cockpit for AI-assisted product building.

Current goal:
Ship v0.1 with Feature Plan, Parking Lot, Pulse Log, and Export.

Initial features:

Now:
- Feature Plan screen
- Parking Lot screen
- Pulse Log screen
- Export screen

Parking Lot:
- AI idea triage
- Phases and releases
- Multi-project support
- Local/cloud AI router
- Real Agent Pulse ingestion
- Git integration
- OpenClaw/Hermes integration

## UX Requirements

The app should be:
- Calm
- Minimal
- Mobile-friendly
- Easy to use
- Not Jira-like
- Not cluttered

Important quick actions:
- Add feature
- Park idea
- Add pulse
- Export context

## v0.1 Definition of Done

The app is done when:
1. The user can edit the project summary.
2. The user can create/edit/delete features.
3. The user can move features between Now, Next, Later, Done.
4. The user can add acceptance criteria to features.
5. The user can create/edit/delete Parking Lot items.
6. The user can manually add Pulse events.
7. Pulse events can link to features.
8. Pulse events display chronologically.
9. Data persists after refresh.
10. Full JSON export works.
11. Pulse JSONL export works.
12. Markdown context export works.
13. `CLAUDE_CONTEXT.md` is useful for AI coding handoff.
14. The app can manage its own BuildPulse development work.

## Forbidden v0.1 Features

Do not implement:
- Multiple projects
- Phases
- Releases
- AI triage
- AI provider settings
- Local/cloud router
- Real agent event ingestion
- OpenClaw integration
- Claude Code integration
- GitHub/Gitea integration
- WebSockets
- Database
- Authentication
- Multi-user support
- Notifications
- Advanced analytics

If tempted, add the idea to Parking Lot instead.

## Suggested Implementation Plan

1. Create React/Vite app.
2. Define TypeScript types matching `docs/DATA_SCHEMA.md`.
3. Implement local storage.
4. Implement project summary.
5. Implement Feature Plan.
6. Implement Parking Lot.
7. Implement Pulse Log.
8. Implement Export functions.
9. Add seed data.
10. Test manually using `docs/TEST_PLAN.md`.

## Suggested Components

```text
AppShell
Navigation
ProjectSummary
FeatureBoard
FeatureCard
FeatureEditor
ParkingLotView
ParkingLotItemCard
ParkingLotItemEditor
PulseLogView
PulseEventForm
PulseEventItem
ExportView
```

## End-of-Task Report Required

After implementation, report:
- What was built
- Files created/changed
- How to run locally
- How to test manually
- Which v0.1 acceptance criteria are met
- Which rough edges remain
- Which ideas were parked

---

## One-shot prompt to give an AI developer/orchestrator

Use this after creating the docs above.

```text
You are the AI developer/orchestrator for BuildPulse.
Read these files before doing anything:
- README.md
- CLAUDE.md
- AGENTS.md
- docs/PRODUCT_BRIEF.md
- docs/SCOPE.md
- docs/ARCHITECTURE.md
- docs/DATA_SCHEMA.md
- docs/UI_SPEC.md
- docs/TEST_PLAN.md
- docs/DECISIONS.md
- docs/PARKING_LOT.md
- docs/EXPORT_FORMATS.md
- docs/AI_DEVELOPER_HANDOFF.md

Your task:
Build BuildPulse v0.1 exactly as scoped.
BuildPulse v0.1 is a local-first, single-project planning cockpit for AI-assisted development.

Required v0.1 views:
1. Feature Plan
2. Parking Lot
3. Pulse Log
4. Export

Required behavior:
- One active project only
- Feature cards in Now / Next / Later / Done
- Parking Lot for distracting ideas
- Manual Pulse Log with future-compatible Pulse event schema
- Local persistence
- JSON export/import
- Pulse JSONL export
- Markdown export including CLAUDE_CONTEXT.md

Hard constraints:
- Do not add multiple projects
- Do not add phases
- Do not add releases
- Do not add AI triage
- Do not add local/cloud router
- Do not add real agent integration
- Do not add backend auth
- Do not add database
- Do not add WebSockets
- Do not add GitHub/OpenClaw/Hermes integration

If you think of useful extra features, add them to Parking Lot or docs/PARKING_LOT.md. Do not implement them.

Before coding:
1. Summarize your understanding of v0.1.
2. Propose the simplest architecture.
3. List files/components you will create.
4. Restate the v0.1 definition of done.

Then implement.

After coding:
1. Run available checks.
2. Provide exact run instructions.
3. Provide manual test steps.
4. List completed acceptance criteria.
5. List rough edges.
6. List parked ideas.
```

## The shortest version of the project direction

BuildPulse v0.1 is a single-project, local-first feature cockpit with Parking Lot, manual Pulse Log, and AI-context export.
It must help me see what I am building, what is active now, what is parked, what happened, and what to hand off to an AI coder next.
Do not build the full Agent Pulse framework yet.

This package is ready to hand to Claude Code, Codex, OpenCode, OpenClaw, Hermes, or another AI orchestrator.