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,324 @@
+# 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.