chore: seed BuildPulse v0.1 documentation package
This commit is contained in:
OpenClaw Bot
@@ -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.
|
||||
@@ -0,0 +1,211 @@
|
||||
# BuildPulse Architecture
|
||||
|
||||
## Architecture Goal
|
||||
|
||||
Keep v0.1 boring, local-first, and easy to understand.
|
||||
BuildPulse should be simple enough for AI coding agents to modify safely without losing context.
|
||||
|
||||
## Recommended v0.1 Stack
|
||||
|
||||
Preferred simple stack:
|
||||
- React
|
||||
- Vite
|
||||
- TypeScript if practical
|
||||
- LocalStorage or IndexedDB
|
||||
- Markdown/JSON export
|
||||
|
||||
Optional if file-backed storage is explicitly wanted:
|
||||
- Tiny Node/Express backend
|
||||
- Files:
|
||||
- `data/project.json`
|
||||
- `data/features/*.json`
|
||||
- `data/parking_lot/*.json`
|
||||
- `data/pulses.jsonl`
|
||||
|
||||
Do not add a database in v0.1.
|
||||
|
||||
## Design Principle
|
||||
|
||||
BuildPulse is pulse-compatible, not pulse-dependent.
|
||||
That means:
|
||||
- Pulse event shape exists from day one.
|
||||
- Events can be manual in v0.1.
|
||||
- Future agents can emit the same event shape later.
|
||||
- No full event bus is required in v0.1.
|
||||
|
||||
## High-Level Modules
|
||||
|
||||
### App Shell
|
||||
|
||||
Responsible for:
|
||||
- Navigation
|
||||
- Layout
|
||||
- Active view
|
||||
- Global app state loading/saving
|
||||
|
||||
Views:
|
||||
- Feature Plan
|
||||
- Parking Lot
|
||||
- Pulse Log
|
||||
- Export
|
||||
|
||||
### Project Store
|
||||
|
||||
Responsible for:
|
||||
- Single project data
|
||||
- Feature cards
|
||||
- Parking Lot items
|
||||
- Pulse events
|
||||
- Import/export
|
||||
|
||||
### Feature Plan Module
|
||||
|
||||
Responsible for:
|
||||
- Feature CRUD
|
||||
- Column movement
|
||||
- Feature detail editing
|
||||
- Acceptance criteria
|
||||
|
||||
### Parking Lot Module
|
||||
|
||||
Responsible for:
|
||||
- Parked idea CRUD
|
||||
- Reason parked
|
||||
- Future placement
|
||||
- Risk
|
||||
|
||||
### Pulse Log Module
|
||||
|
||||
Responsible for:
|
||||
- Manual Pulse event creation
|
||||
- Chronological event display
|
||||
- Feature-linked filtering
|
||||
- Trace ID grouping later
|
||||
|
||||
### Export Module
|
||||
|
||||
Responsible for:
|
||||
- Full JSON export/import
|
||||
- JSONL Pulse export
|
||||
- Markdown context export
|
||||
- `CLAUDE_CONTEXT.md` generation
|
||||
|
||||
## Suggested Source Structure
|
||||
|
||||
```text
|
||||
src/
|
||||
main.tsx
|
||||
App.tsx
|
||||
components/
|
||||
AppShell.tsx
|
||||
Navigation.tsx
|
||||
EmptyState.tsx
|
||||
Modal.tsx
|
||||
TextInput.tsx
|
||||
TextArea.tsx
|
||||
Select.tsx
|
||||
features/
|
||||
feature-plan/
|
||||
FeatureBoard.tsx
|
||||
FeatureCard.tsx
|
||||
FeatureDetail.tsx
|
||||
featureUtils.ts
|
||||
parking-lot/
|
||||
ParkingLotView.tsx
|
||||
ParkingLotItemCard.tsx
|
||||
ParkingLotItemDetail.tsx
|
||||
pulse-log/
|
||||
PulseLogView.tsx
|
||||
PulseEventForm.tsx
|
||||
PulseEventItem.tsx
|
||||
pulseUtils.ts
|
||||
export/
|
||||
ExportView.tsx
|
||||
exportMarkdown.ts
|
||||
exportJson.ts
|
||||
project/
|
||||
ProjectSummary.tsx
|
||||
projectDefaults.ts
|
||||
store/
|
||||
types.ts
|
||||
appStore.ts
|
||||
storage.ts
|
||||
migrations.ts
|
||||
utils/
|
||||
ids.ts
|
||||
dates.ts
|
||||
validation.ts
|
||||
```
|
||||
|
||||
## Storage Strategy
|
||||
|
||||
### Fastest v0.1
|
||||
|
||||
Use browser storage.
|
||||
- Store one serialized app state object.
|
||||
- Include a schema version.
|
||||
- Support export/import to avoid lock-in.
|
||||
|
||||
Example key:
|
||||
|
||||
```text
|
||||
buildpulse.appState.v1
|
||||
```
|
||||
|
||||
### Future File-Backed Mode
|
||||
|
||||
Later, the same data can be saved as:
|
||||
|
||||
```text
|
||||
data/
|
||||
project.json
|
||||
features/
|
||||
parking_lot/
|
||||
pulses.jsonl
|
||||
```
|
||||
|
||||
Do not build this unless explicitly requested for v0.1.
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
Every stored state must include:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "0.1.0"
|
||||
}
|
||||
```
|
||||
|
||||
Add migrations later if needed.
|
||||
|
||||
## Future Agent Pulse Compatibility
|
||||
|
||||
v0.1 Pulse events should already include:
|
||||
- `id`
|
||||
- `timestamp`
|
||||
- `project_id`
|
||||
- `feature_id`
|
||||
- `source`
|
||||
- `agent_id`
|
||||
- `pulse_type`
|
||||
- `message`
|
||||
- `structured_payload`
|
||||
- `confidence_score`
|
||||
- `evidence_refs`
|
||||
- `trace_id`
|
||||
|
||||
Even if many fields are optional or manually filled.
|
||||
|
||||
## Explicit Non-Architecture
|
||||
|
||||
Do not introduce:
|
||||
- Redux unless needed
|
||||
- Complex state machines
|
||||
- Backend services
|
||||
- Event buses
|
||||
- WebSockets
|
||||
- Plugins
|
||||
- Agent daemons
|
||||
- Multi-user permissions
|
||||
|
||||
Keep it simple.
|
||||
@@ -0,0 +1,226 @@
|
||||
# BuildPulse Data Schema
|
||||
|
||||
## Schema Version
|
||||
|
||||
Current schema version:
|
||||
|
||||
```text
|
||||
0.1.0
|
||||
```
|
||||
|
||||
## App State
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "0.1.0",
|
||||
"project": {},
|
||||
"features": [],
|
||||
"parking_lot": [],
|
||||
"pulses": [],
|
||||
"settings": {}
|
||||
}
|
||||
```
|
||||
|
||||
## Project
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "project_buildpulse",
|
||||
"name": "BuildPulse",
|
||||
"one_line_pitch": "A local-first planning cockpit for AI-assisted product building.",
|
||||
"description": "BuildPulse helps capture features, park distracting ideas, log progress as Pulse events, and export clean context for AI coding agents.",
|
||||
"current_goal": "Ship v0.1 with Feature Plan, Parking Lot, Pulse Log, and Export.",
|
||||
"notes": "",
|
||||
"created_at": "2026-05-06T00:00:00+02:00",
|
||||
"updated_at": "2026-05-06T00:00:00+02:00"
|
||||
}
|
||||
```
|
||||
|
||||
## Feature
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "feature_plan_screen",
|
||||
"title": "Feature Plan screen",
|
||||
"description": "Create and manage feature cards in Now, Next, Later, and Done.",
|
||||
"column": "now",
|
||||
"priority": "must",
|
||||
"status": "ready",
|
||||
"acceptance_criteria": [
|
||||
"User can create a feature card.",
|
||||
"User can edit feature title and description.",
|
||||
"User can move feature between columns."
|
||||
],
|
||||
"scope_notes": "No phases or releases in v0.1.",
|
||||
"created_at": "2026-05-06T00:00:00+02:00",
|
||||
"updated_at": "2026-05-06T00:00:00+02:00"
|
||||
}
|
||||
```
|
||||
|
||||
## Feature Columns
|
||||
|
||||
Allowed column values:
|
||||
- `now`
|
||||
- `next`
|
||||
- `later`
|
||||
- `done`
|
||||
|
||||
## Feature Priority
|
||||
|
||||
Allowed priority values:
|
||||
- `must`
|
||||
- `should`
|
||||
- `could`
|
||||
- `later`
|
||||
|
||||
## Feature Status
|
||||
|
||||
Allowed status values:
|
||||
- `idea`
|
||||
- `shaping`
|
||||
- `ready`
|
||||
- `building`
|
||||
- `testing`
|
||||
- `done`
|
||||
- `parked`
|
||||
- `rejected`
|
||||
|
||||
In v0.1, column is more important than status.
|
||||
|
||||
## Parking Lot Item
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "parked_ai_triage",
|
||||
"title": "AI idea triage",
|
||||
"description": "Use AI to classify new ideas into Now, Next, Later, Parking Lot, or Reject.",
|
||||
"reason_parked": "Useful, but v0.1 must prove the manual workflow first.",
|
||||
"possible_future_placement": "v0.2",
|
||||
"risk_level": "medium",
|
||||
"created_at": "2026-05-06T00:00:00+02:00",
|
||||
"updated_at": "2026-05-06T00:00:00+02:00"
|
||||
}
|
||||
```
|
||||
|
||||
## Parking Lot Risk Level
|
||||
|
||||
Allowed `risk_level` values:
|
||||
- `low`
|
||||
- `medium`
|
||||
- `high`
|
||||
- `dangerous`
|
||||
|
||||
## Pulse Event
|
||||
|
||||
Pulse events are append-friendly and future-compatible with Agent Pulse.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "pulse_001",
|
||||
"timestamp": "2026-05-06T00:00:00+02:00",
|
||||
"project_id": "project_buildpulse",
|
||||
"feature_id": "feature_plan_screen",
|
||||
"source": "manual",
|
||||
"agent_id": "jimmi",
|
||||
"pulse_type": "INTENT",
|
||||
"message": "Start implementing the Feature Plan screen.",
|
||||
"structured_payload": {},
|
||||
"confidence_score": 0.9,
|
||||
"evidence_refs": [],
|
||||
"trace_id": "session_001"
|
||||
}
|
||||
```
|
||||
|
||||
## Pulse Types
|
||||
|
||||
Allowed `pulse_type` values:
|
||||
- `INTENT`
|
||||
- `ACTION`
|
||||
- `RESULT`
|
||||
- `BLOCKER`
|
||||
- `DECISION`
|
||||
- `PARKED_IDEA`
|
||||
- `TEST_RESULT`
|
||||
- `SESSION_START`
|
||||
- `SESSION_END`
|
||||
- `REFLECTION`
|
||||
|
||||
## Pulse Source
|
||||
|
||||
Suggested `source` values:
|
||||
- `manual`
|
||||
- `user`
|
||||
- `claude_code`
|
||||
- `codex`
|
||||
- `opencode`
|
||||
- `openclaw`
|
||||
- `hermes`
|
||||
- `local_llm`
|
||||
- `system`
|
||||
|
||||
v0.1 should not require strict enforcement beyond basic string handling.
|
||||
|
||||
## Evidence Refs
|
||||
|
||||
Evidence refs are references to outputs, tests, commits, screenshots, files, or notes.
|
||||
|
||||
Simple v0.1 form:
|
||||
|
||||
```json
|
||||
[
|
||||
"Manual test passed",
|
||||
"Exported CLAUDE_CONTEXT.md",
|
||||
"Commit abc123"
|
||||
]
|
||||
```
|
||||
|
||||
Later form may become:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"type": "file",
|
||||
"label": "FEATURE_PLAN.md",
|
||||
"url": ""
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Settings
|
||||
|
||||
Minimal v0.1 settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"theme": "light",
|
||||
"default_agent_id": "jimmi"
|
||||
}
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
Required project fields:
|
||||
- `id`
|
||||
- `name`
|
||||
|
||||
Required feature fields:
|
||||
- `id`
|
||||
- `title`
|
||||
- `column`
|
||||
|
||||
Required parking lot fields:
|
||||
- `id`
|
||||
- `title`
|
||||
|
||||
Required pulse fields:
|
||||
- `id`
|
||||
- `timestamp`
|
||||
- `project_id`
|
||||
- `pulse_type`
|
||||
- `message`
|
||||
|
||||
## Export Rule
|
||||
|
||||
Exports should preserve IDs exactly.
|
||||
|
||||
Do not regenerate IDs during export/import unless resolving duplicates is required.
|
||||
@@ -0,0 +1,127 @@
|
||||
# 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`, `structured_payload`, and `evidence_refs`.
|
||||
- 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 — Local-First Storage
|
||||
|
||||
Date:
|
||||
2026-05-06
|
||||
|
||||
Decision:
|
||||
BuildPulse v0.1 uses local-first storage.
|
||||
|
||||
Reason:
|
||||
This keeps the first version simple, fast, private, and easy to run.
|
||||
|
||||
Consequences:
|
||||
- No database.
|
||||
- No auth.
|
||||
- Export/import is important to avoid lock-in.
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,158 @@
|
||||
# BuildPulse Export Formats
|
||||
|
||||
## Export Goals
|
||||
|
||||
Exports must support:
|
||||
1. Backup/restore
|
||||
2. AI coding agent handoff
|
||||
3. Future Agent Pulse compatibility
|
||||
4. Human-readable project review
|
||||
|
||||
## Export Types
|
||||
|
||||
v0.1 supports:
|
||||
- Full JSON export
|
||||
- Pulse JSONL export
|
||||
- Markdown context package
|
||||
|
||||
## Full JSON Export
|
||||
|
||||
File name:
|
||||
|
||||
```text
|
||||
buildpulse-export.json
|
||||
```
|
||||
|
||||
Shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "0.1.0",
|
||||
"exported_at": "2026-05-06T00:00:00+02:00",
|
||||
"project": {},
|
||||
"features": [],
|
||||
"parking_lot": [],
|
||||
"pulses": [],
|
||||
"settings": {}
|
||||
}
|
||||
```
|
||||
|
||||
## Pulse JSONL Export
|
||||
|
||||
File name:
|
||||
|
||||
```text
|
||||
pulses.jsonl
|
||||
```
|
||||
|
||||
Rules:
|
||||
- One JSON object per line.
|
||||
- Each line is one Pulse event.
|
||||
- Preserve event IDs.
|
||||
- Preserve timestamps.
|
||||
- Do not wrap in an array.
|
||||
|
||||
Example:
|
||||
|
||||
```jsonl
|
||||
{"id":"pulse_001","timestamp":"2026-05-06T00:00:00+02:00","project_id":"project_buildpulse","feature_id":"feature_plan_screen","source":"manual","agent_id":"jimmi","pulse_type":"INTENT","message":"Start implementing Feature Plan.","structured_payload":{},"confidence_score":0.9,"evidence_refs":[],"trace_id":"session_001"}
|
||||
{"id":"pulse_002","timestamp":"2026-05-06T00:30:00+02:00","project_id":"project_buildpulse","feature_id":"feature_plan_screen","source":"claude_code","agent_id":"claude_code","pulse_type":"RESULT","message":"Feature card creation implemented.","structured_payload":{},"confidence_score":0.8,"evidence_refs":["Manual test passed"],"trace_id":"session_001"}
|
||||
```
|
||||
|
||||
## Markdown Package
|
||||
|
||||
The Markdown export should generate these files:
|
||||
- `PROJECT_SUMMARY.md`
|
||||
- `FEATURE_PLAN.md`
|
||||
- `PARKING_LOT.md`
|
||||
- `PULSE_LOG.md`
|
||||
- `CLAUDE_CONTEXT.md`
|
||||
|
||||
## PROJECT_SUMMARY.md
|
||||
|
||||
Must include:
|
||||
- Project name
|
||||
- One-line pitch
|
||||
- Description
|
||||
- Current goal
|
||||
- Notes
|
||||
|
||||
## FEATURE_PLAN.md
|
||||
|
||||
Must include features grouped by:
|
||||
- Now
|
||||
- Next
|
||||
- Later
|
||||
- Done
|
||||
|
||||
Each feature should include:
|
||||
- Title
|
||||
- Description
|
||||
- Priority
|
||||
- Acceptance criteria
|
||||
- Scope notes
|
||||
|
||||
## PARKING_LOT.md
|
||||
|
||||
Must include:
|
||||
- Title
|
||||
- Description
|
||||
- Reason parked
|
||||
- Possible future placement
|
||||
- Risk level
|
||||
|
||||
## PULSE_LOG.md
|
||||
|
||||
Must include recent Pulse events, newest first or chronological.
|
||||
|
||||
Each pulse should include:
|
||||
- Timestamp
|
||||
- Pulse type
|
||||
- Feature
|
||||
- Source/agent
|
||||
- Message
|
||||
- Confidence
|
||||
- Evidence refs
|
||||
|
||||
## CLAUDE_CONTEXT.md
|
||||
|
||||
This is the most important AI handoff file.
|
||||
|
||||
It should include:
|
||||
|
||||
# AI Coding Context
|
||||
## Project
|
||||
<Project summary>
|
||||
## Current Goal
|
||||
<Current project goal>
|
||||
## Active Features
|
||||
<Now features>
|
||||
## Next Features
|
||||
<Next features>
|
||||
## Done Features
|
||||
<Done features>
|
||||
## Parking Lot / Do Not Implement Yet
|
||||
<Parking lot items>
|
||||
## Recent Pulse Events
|
||||
<Recent important pulses>
|
||||
## Instructions for AI Developer
|
||||
- Only work on the selected feature.
|
||||
- Do not implement Parking Lot items.
|
||||
- Preserve working behavior.
|
||||
- Report changes and test steps.
|
||||
|
||||
## Import Rules
|
||||
|
||||
When importing JSON:
|
||||
- Validate schema version.
|
||||
- Validate required fields.
|
||||
- Show useful error if invalid.
|
||||
- Preserve IDs.
|
||||
- Avoid silent data loss.
|
||||
- If schema version differs, warn user.
|
||||
|
||||
## Copy-to-Clipboard
|
||||
|
||||
If downloading multiple files is complex in v0.1, support copying each Markdown output to clipboard.
|
||||
|
||||
Download can be added later.
|
||||
@@ -0,0 +1,222 @@
|
||||
# BuildPulse Parking Lot
|
||||
|
||||
This file contains useful ideas that are intentionally not part of v0.1.
|
||||
Parking ideas is a success behavior, not a failure.
|
||||
|
||||
## AI Idea Triage
|
||||
|
||||
Description:
|
||||
Use AI to classify new ideas into Now, Next, Later, Parking Lot, or Reject.
|
||||
|
||||
Reason parked:
|
||||
Manual workflow should be proven first.
|
||||
|
||||
Possible version:
|
||||
v0.2
|
||||
|
||||
Risk:
|
||||
Medium
|
||||
|
||||
## AI Scope Creep Detection
|
||||
|
||||
Description:
|
||||
AI reviews a proposed feature and warns if it violates current scope.
|
||||
|
||||
Reason parked:
|
||||
Requires AI integration and context handling.
|
||||
|
||||
Possible version:
|
||||
v0.2
|
||||
|
||||
Risk:
|
||||
Medium
|
||||
|
||||
## Acceptance Criteria Generator
|
||||
|
||||
Description:
|
||||
AI generates testable acceptance criteria for a feature card.
|
||||
|
||||
Reason parked:
|
||||
Useful but not needed for manual v0.1.
|
||||
|
||||
Possible version:
|
||||
v0.2
|
||||
|
||||
Risk:
|
||||
Low
|
||||
|
||||
## Phases and Releases
|
||||
|
||||
Description:
|
||||
Add formal project phases and release planning.
|
||||
|
||||
Reason parked:
|
||||
v0.1 only needs Now/Next/Later/Done.
|
||||
|
||||
Possible version:
|
||||
v0.3
|
||||
|
||||
Risk:
|
||||
Medium
|
||||
|
||||
## Session View
|
||||
|
||||
Description:
|
||||
Add a dedicated session timer and session dashboard.
|
||||
|
||||
Reason parked:
|
||||
In v0.1, sessions are represented as Pulse events.
|
||||
|
||||
Possible version:
|
||||
v0.4
|
||||
|
||||
Risk:
|
||||
Medium
|
||||
|
||||
## Claude/Codex Prompt Generator
|
||||
|
||||
Description:
|
||||
Generate ready-to-paste prompts for Claude Code, Codex, OpenCode, or OpenClaw based on selected feature.
|
||||
|
||||
Reason parked:
|
||||
Requires feature plan and export to work first.
|
||||
|
||||
Possible version:
|
||||
v0.4
|
||||
|
||||
Risk:
|
||||
Low
|
||||
|
||||
## Local/Cloud AI Router
|
||||
|
||||
Description:
|
||||
Track which AI tasks should use local LLMs vs cloud providers.
|
||||
|
||||
Reason parked:
|
||||
Important later, but not required for planning cockpit v0.1.
|
||||
|
||||
Possible version:
|
||||
v0.5
|
||||
|
||||
Risk:
|
||||
High
|
||||
|
||||
## Local Model Capability Lab
|
||||
|
||||
Description:
|
||||
Track local models, hardware, use cases, speed, quality, and recommended tasks.
|
||||
|
||||
Reason parked:
|
||||
Useful but could become a distraction before BuildPulse is useful.
|
||||
|
||||
Possible version:
|
||||
v0.5
|
||||
|
||||
Risk:
|
||||
High
|
||||
|
||||
## File-Backed Storage
|
||||
|
||||
Description:
|
||||
Store features as JSON files and pulses as JSONL on disk.
|
||||
|
||||
Reason parked:
|
||||
More future-compatible with agents, but browser local storage is faster for v0.1.
|
||||
|
||||
Possible version:
|
||||
v0.6 or earlier if explicitly chosen.
|
||||
|
||||
Risk:
|
||||
Medium
|
||||
|
||||
## Real Agent Pulse Ingestion
|
||||
|
||||
Description:
|
||||
Allow external agents/tools to submit Pulse events via API.
|
||||
|
||||
Reason parked:
|
||||
This is the beginning of the actual Agent Pulse framework and should not be built before manual pulse workflows are proven.
|
||||
|
||||
Possible version:
|
||||
v1.0
|
||||
|
||||
Risk:
|
||||
High
|
||||
|
||||
## WebSocket Timeline
|
||||
|
||||
Description:
|
||||
Show live agent activity in real time.
|
||||
|
||||
Reason parked:
|
||||
Requires backend/event infrastructure.
|
||||
|
||||
Possible version:
|
||||
v1.0+
|
||||
|
||||
Risk:
|
||||
High
|
||||
|
||||
## GitHub/Gitea Integration
|
||||
|
||||
Description:
|
||||
Link pulses/features to commits, branches, issues, and PRs.
|
||||
|
||||
Reason parked:
|
||||
Useful later but not needed for v0.1.
|
||||
|
||||
Possible version:
|
||||
v1.0+
|
||||
|
||||
Risk:
|
||||
Medium
|
||||
|
||||
## OpenClaw/Hermes Integration
|
||||
|
||||
Description:
|
||||
Read OpenClaw/Hermes heartbeats, agent status, and task outputs into BuildPulse.
|
||||
|
||||
Reason parked:
|
||||
Important long-term, but too complex for v0.1.
|
||||
|
||||
Possible version:
|
||||
v1.0+
|
||||
|
||||
Risk:
|
||||
High
|
||||
|
||||
## Multi-Project Support
|
||||
|
||||
Description:
|
||||
Allow multiple projects in the same BuildPulse instance.
|
||||
|
||||
Reason parked:
|
||||
Single-project workflow should be proven first.
|
||||
|
||||
Possible version:
|
||||
v0.6+
|
||||
|
||||
Risk:
|
||||
Medium
|
||||
|
||||
## Full Agent Pulse Framework
|
||||
|
||||
Description:
|
||||
Event-driven autonomous agent observability and coordination layer.
|
||||
Includes:
|
||||
- Append-only event log
|
||||
- Agent ownership
|
||||
- Handoff protocol
|
||||
- Progress engine
|
||||
- Safety gates
|
||||
- WebSockets
|
||||
- Plugin system
|
||||
|
||||
Reason parked:
|
||||
This is the end-state architecture, not the first build.
|
||||
|
||||
Possible version:
|
||||
v2.0
|
||||
|
||||
Risk:
|
||||
Dangerous
|
||||
@@ -0,0 +1,100 @@
|
||||
# Product Brief — BuildPulse
|
||||
|
||||
## Product Name
|
||||
|
||||
BuildPulse
|
||||
|
||||
## One-Line Description
|
||||
|
||||
BuildPulse is a local-first planning cockpit that helps a solo builder capture features, park distracting ideas, log progress as Pulse events, and export clean context for AI coding agents.
|
||||
|
||||
## Problem
|
||||
|
||||
The user has many ideas and several AI coding tools, but lacks a stable system for:
|
||||
- Capturing new ideas without derailing active work
|
||||
- Deciding what belongs now vs later
|
||||
- Following a clear feature plan
|
||||
- Keeping context visible across AI coding sessions
|
||||
- Preventing working builds from being broken by random new features
|
||||
- Seeing progress based on evidence instead of vague task status
|
||||
- Preparing clean handoff context for Claude Code, Codex, OpenCode, OpenClaw, or other agents
|
||||
|
||||
## Target User
|
||||
|
||||
Primary target user:
|
||||
- A solo builder using AI coding tools to create apps, games, and tools.
|
||||
- The user is technically curious but does not want to manually manage complex development workflows.
|
||||
- The user benefits from ADHD-friendly guardrails, visible plans, parking lots, and short work sessions.
|
||||
|
||||
Secondary future users:
|
||||
- Indie hackers
|
||||
- AI-assisted builders
|
||||
- Small teams working with autonomous coding agents
|
||||
- Users who want a lightweight alternative to Jira/task boards for AI-assisted work
|
||||
|
||||
## Core User Need
|
||||
|
||||
The user needs one trusted place to answer:
|
||||
- What am I building?
|
||||
- What is currently in scope?
|
||||
- What should I work on next?
|
||||
- Where should this new idea go?
|
||||
- What has changed?
|
||||
- What can I safely hand off to an AI coding agent?
|
||||
|
||||
## v0.1 Product Promise
|
||||
|
||||
BuildPulse v0.1 lets the user manage one active project with:
|
||||
- A simple feature plan
|
||||
- A parking lot for distracting ideas
|
||||
- A manual Pulse log
|
||||
- Exportable project context
|
||||
|
||||
## Core Workflow
|
||||
|
||||
1. User opens BuildPulse.
|
||||
2. User sees the current project and active feature plan.
|
||||
3. User adds or edits feature cards.
|
||||
4. User parks distracting ideas instead of adding them to active scope.
|
||||
5. User logs progress using Pulse events.
|
||||
6. User exports clean Markdown context for an AI coder.
|
||||
7. AI coder works from exported context.
|
||||
8. User logs results back into BuildPulse.
|
||||
|
||||
## Product Positioning
|
||||
|
||||
BuildPulse is not:
|
||||
- Jira
|
||||
- Trello clone
|
||||
- Full agent framework
|
||||
- Full project management suite
|
||||
- Autonomous AI orchestration system
|
||||
- Multi-user SaaS platform
|
||||
|
||||
BuildPulse is:
|
||||
- A calm cockpit for solo AI-assisted building
|
||||
- A pulse-compatible planning layer
|
||||
- A scope guardrail
|
||||
- A structured bridge between human ideas and AI coding agents
|
||||
|
||||
## Success Criteria for v0.1
|
||||
|
||||
v0.1 succeeds if the user can use it to plan and manage BuildPulse itself, then use it to plan another project such as Crimson Drive.
|
||||
|
||||
## First Dogfood Project
|
||||
|
||||
BuildPulse should track itself as the first project.
|
||||
|
||||
Initial feature groups:
|
||||
|
||||
Now:
|
||||
- Feature Plan
|
||||
- Parking Lot
|
||||
- Pulse Log
|
||||
- Export
|
||||
|
||||
Later:
|
||||
- AI triage
|
||||
- Phases/releases
|
||||
- Local/cloud router
|
||||
- Real Agent Pulse ingestion
|
||||
+135
@@ -0,0 +1,135 @@
|
||||
# BuildPulse Roadmap
|
||||
|
||||
## Philosophy
|
||||
|
||||
Each version must be useful on its own.
|
||||
Do not build future architecture before the current manual workflow is proven.
|
||||
|
||||
## v0.1 — Single-Project Planning Cockpit
|
||||
|
||||
Goal:
|
||||
Create the smallest useful cockpit for one project.
|
||||
|
||||
Includes:
|
||||
- Single project summary
|
||||
- Feature Plan
|
||||
- Parking Lot
|
||||
- Manual Pulse Log
|
||||
- Markdown/JSON/JSONL export
|
||||
- Local persistence
|
||||
|
||||
Does not include:
|
||||
- AI
|
||||
- Phases
|
||||
- Releases
|
||||
- Multiple projects
|
||||
- Real agent integration
|
||||
|
||||
## v0.2 — AI Idea Placement
|
||||
|
||||
Goal:
|
||||
Use AI to help classify new ideas.
|
||||
|
||||
Potential features:
|
||||
- AI classify idea as Now / Next / Later / Parking Lot / Reject
|
||||
- AI suggest reason for placement
|
||||
- AI suggest smallest safe version
|
||||
- AI detect scope creep
|
||||
- AI generate acceptance criteria draft
|
||||
|
||||
Build only one or two AI actions first.
|
||||
|
||||
Highest-value first AI action:
|
||||
|
||||
```text
|
||||
Classify new idea and suggest placement.
|
||||
```
|
||||
|
||||
## v0.3 — Phases and Releases
|
||||
|
||||
Goal:
|
||||
Add structured implementation planning.
|
||||
|
||||
Potential features:
|
||||
- Phases
|
||||
- Releases
|
||||
- Definition of done
|
||||
- Forbidden features per release
|
||||
- Required vs optional features
|
||||
- Release readiness view
|
||||
|
||||
## v0.4 — Session Prompt Generator
|
||||
|
||||
Goal:
|
||||
Generate clean prompts for AI coding agents.
|
||||
|
||||
Potential features:
|
||||
- Start 30-minute session from feature
|
||||
- Generate Claude Code/Codex prompt
|
||||
- Include do-not-touch list
|
||||
- Include acceptance criteria
|
||||
- Include recent pulse context
|
||||
- End-session summary template
|
||||
|
||||
## v0.5 — Local/Cloud AI Assistant
|
||||
|
||||
Goal:
|
||||
Start learning where local LLMs are good enough.
|
||||
|
||||
Potential features:
|
||||
- Configure local endpoint manually
|
||||
- Use local LLM for summaries
|
||||
- Use local LLM for feature classification
|
||||
- Track model usefulness
|
||||
- Manual cloud fallback
|
||||
|
||||
## v1.0 — Agent Pulse Ingestion MVP
|
||||
|
||||
Goal:
|
||||
Allow real agents/tools to submit Pulse events.
|
||||
|
||||
Potential features:
|
||||
- Simple HTTP API for Pulse events
|
||||
- Append-only pulse event store
|
||||
- Real-time or refresh-based timeline
|
||||
- Feature state updated from events
|
||||
- Basic progress computation
|
||||
- Safety/event validation
|
||||
|
||||
## v1.5 — Agent Observability
|
||||
|
||||
Goal:
|
||||
Show real live-ish agent activity.
|
||||
|
||||
Potential features:
|
||||
- Agent activity view
|
||||
- Blocker/risk view
|
||||
- Handoff events
|
||||
- Evidence refs
|
||||
- Test result parsing
|
||||
- Git commit refs
|
||||
|
||||
## v2.0 — Agent Pulse Framework
|
||||
|
||||
Goal:
|
||||
Become a real event-driven nervous system for autonomous agents.
|
||||
|
||||
Potential features:
|
||||
- WebSocket stream
|
||||
- Event subscriptions
|
||||
- Agent coordination protocol
|
||||
- Ownership claims
|
||||
- Handoff handling
|
||||
- Progress engine
|
||||
- Constraints and approval gates
|
||||
- Plugin system
|
||||
|
||||
## Long-Term Vision
|
||||
|
||||
BuildPulse becomes the human cockpit for:
|
||||
- Feature planning
|
||||
- Idea maturation
|
||||
- Scope control
|
||||
- AI agent work visibility
|
||||
- Local/cloud AI routing
|
||||
- Autonomous agent observability
|
||||
+171
@@ -0,0 +1,171 @@
|
||||
# BuildPulse v0.1 Scope
|
||||
|
||||
## Release Goal
|
||||
|
||||
Build a tiny, useful, single-project planning cockpit with pulse-compatible progress logging and exportable AI handoff context.
|
||||
|
||||
## v0.1 Core Question
|
||||
|
||||
Can BuildPulse help the user keep one project scoped, visible, and handoff-ready for AI-assisted development?
|
||||
|
||||
## In Scope
|
||||
|
||||
### 1. Single Project
|
||||
|
||||
The app supports one active project.
|
||||
The project has:
|
||||
- Name
|
||||
- One-line pitch
|
||||
- Description
|
||||
- Current goal
|
||||
- Notes
|
||||
|
||||
No multiple projects in v0.1.
|
||||
|
||||
### 2. Feature Plan
|
||||
|
||||
The user can create, edit, delete, and organize features.
|
||||
|
||||
Feature columns:
|
||||
- Now
|
||||
- Next
|
||||
- Later
|
||||
- Done
|
||||
|
||||
Feature fields:
|
||||
- Title
|
||||
- Description
|
||||
- Status/column
|
||||
- Priority
|
||||
- Acceptance criteria
|
||||
- Scope notes
|
||||
- Created date
|
||||
- Updated date
|
||||
|
||||
### 3. Parking Lot
|
||||
|
||||
The user can add, edit, delete, and review parked ideas.
|
||||
|
||||
Parking Lot item fields:
|
||||
- Title
|
||||
- Description
|
||||
- Reason parked
|
||||
- Possible future placement
|
||||
- Risk level
|
||||
- Created date
|
||||
|
||||
### 4. Pulse Log
|
||||
|
||||
The user can manually add Pulse events.
|
||||
|
||||
Pulse event fields:
|
||||
- Timestamp
|
||||
- Feature link, optional
|
||||
- Source/agent
|
||||
- Pulse type
|
||||
- Message
|
||||
- Confidence score
|
||||
- Evidence refs
|
||||
- Trace ID, optional
|
||||
|
||||
Pulse types:
|
||||
- INTENT
|
||||
- ACTION
|
||||
- RESULT
|
||||
- BLOCKER
|
||||
- DECISION
|
||||
- PARKED_IDEA
|
||||
- TEST_RESULT
|
||||
- SESSION_START
|
||||
- SESSION_END
|
||||
- REFLECTION
|
||||
|
||||
### 5. Export
|
||||
|
||||
The user can export:
|
||||
- Full project JSON
|
||||
- Pulse log as JSONL
|
||||
- Markdown context package
|
||||
|
||||
Markdown exports:
|
||||
- PROJECT_SUMMARY.md
|
||||
- FEATURE_PLAN.md
|
||||
- PARKING_LOT.md
|
||||
- PULSE_LOG.md
|
||||
- CLAUDE_CONTEXT.md
|
||||
|
||||
### 6. Local Persistence
|
||||
|
||||
The app persists data locally.
|
||||
Acceptable v0.1 storage:
|
||||
- LocalStorage
|
||||
- IndexedDB
|
||||
- JSON file export/import
|
||||
|
||||
No database required.
|
||||
|
||||
## Out of Scope for v0.1
|
||||
|
||||
Do not implement:
|
||||
- Multiple projects
|
||||
- Phases
|
||||
- Releases
|
||||
- AI triage
|
||||
- AI model provider settings
|
||||
- Local/cloud model routing
|
||||
- Real agent integration
|
||||
- OpenClaw integration
|
||||
- Claude Code direct integration
|
||||
- GitHub/Gitea integration
|
||||
- WebSockets
|
||||
- Backend authentication
|
||||
- Database
|
||||
- Multi-user collaboration
|
||||
- Notifications
|
||||
- Advanced analytics
|
||||
- Dependency graph
|
||||
- Calendar planning
|
||||
- Native mobile app
|
||||
- Automated progress computation
|
||||
|
||||
## Scope Guardrail
|
||||
|
||||
Any idea not required for v0.1 must be placed in Parking Lot.
|
||||
|
||||
## v0.1 Definition of Done
|
||||
|
||||
BuildPulse v0.1 is done when:
|
||||
1. The user can edit the single project summary.
|
||||
2. The user can add feature cards.
|
||||
3. The user can move features between Now, Next, Later, and Done.
|
||||
4. The user can add acceptance criteria to a feature.
|
||||
5. The user can add Parking Lot items.
|
||||
6. The user can manually add Pulse events.
|
||||
7. Pulse events can be linked to features.
|
||||
8. Pulse events display in chronological order.
|
||||
9. The app persists data locally after refresh.
|
||||
10. The user can export JSON.
|
||||
11. The user can export Pulse events as JSONL.
|
||||
12. The user can export Markdown context.
|
||||
13. The exported `CLAUDE_CONTEXT.md` is useful as an AI coding handoff.
|
||||
14. The app can be used to manage BuildPulse itself.
|
||||
|
||||
## v0.1 First Data Seed
|
||||
|
||||
On first run, optionally seed the app with BuildPulse as the active project.
|
||||
|
||||
Suggested starter features:
|
||||
|
||||
Now:
|
||||
- Feature Plan screen
|
||||
- Parking Lot screen
|
||||
- Pulse Log screen
|
||||
- Export screen
|
||||
|
||||
Parking Lot:
|
||||
- AI triage
|
||||
- Phases/releases
|
||||
- Multi-project support
|
||||
- Local/cloud model router
|
||||
- Real Agent Pulse event ingestion
|
||||
- Git integration
|
||||
@@ -0,0 +1,233 @@
|
||||
# BuildPulse v0.1 Test Plan
|
||||
|
||||
## Test Goal
|
||||
|
||||
Verify that BuildPulse v0.1 can manage one project, protect scope, log progress, and export useful AI handoff context.
|
||||
|
||||
## Manual Test Group 1 — Project Summary
|
||||
|
||||
### Test 1.1: Edit project summary
|
||||
|
||||
Steps:
|
||||
1. Open app.
|
||||
2. Edit project name.
|
||||
3. Edit one-line pitch.
|
||||
4. Edit current goal.
|
||||
5. Refresh page.
|
||||
|
||||
Expected:
|
||||
- Edited values persist after refresh.
|
||||
|
||||
### Test 1.2: Empty project fields
|
||||
|
||||
Steps:
|
||||
1. Clear optional project fields.
|
||||
2. Save.
|
||||
3. Refresh.
|
||||
|
||||
Expected:
|
||||
- App does not crash.
|
||||
- Empty states are readable.
|
||||
|
||||
## Manual Test Group 2 — Feature Plan
|
||||
|
||||
### Test 2.1: Add feature
|
||||
|
||||
Steps:
|
||||
1. Open Feature Plan.
|
||||
2. Add new feature.
|
||||
3. Enter title and description.
|
||||
4. Save.
|
||||
|
||||
Expected:
|
||||
- Feature appears in default column.
|
||||
- Feature persists after refresh.
|
||||
|
||||
### Test 2.2: Move feature
|
||||
|
||||
Steps:
|
||||
1. Move a feature from Now to Next.
|
||||
2. Move it to Later.
|
||||
3. Move it to Done.
|
||||
|
||||
Expected:
|
||||
- Feature appears in the correct column each time.
|
||||
- State persists after refresh.
|
||||
|
||||
### Test 2.3: Edit acceptance criteria
|
||||
|
||||
Steps:
|
||||
1. Open feature detail.
|
||||
2. Add acceptance criteria.
|
||||
3. Save and close.
|
||||
4. Reopen feature.
|
||||
|
||||
Expected:
|
||||
- Acceptance criteria are saved and visible.
|
||||
|
||||
### Test 2.4: Delete feature
|
||||
|
||||
Steps:
|
||||
1. Create a test feature.
|
||||
2. Delete it.
|
||||
|
||||
Expected:
|
||||
- Feature is removed.
|
||||
- App remains stable.
|
||||
- Related pulse events are either preserved with missing feature label or handled gracefully.
|
||||
|
||||
## Manual Test Group 3 — Parking Lot
|
||||
|
||||
### Test 3.1: Add parked idea
|
||||
|
||||
Steps:
|
||||
1. Open Parking Lot.
|
||||
2. Add an idea.
|
||||
3. Add reason parked and risk level.
|
||||
|
||||
Expected:
|
||||
- Item appears in Parking Lot.
|
||||
- Item persists after refresh.
|
||||
|
||||
### Test 3.2: Convert parked idea to feature
|
||||
|
||||
If implemented in v0.1:
|
||||
|
||||
Steps:
|
||||
1. Select Parking Lot item.
|
||||
2. Convert to feature.
|
||||
|
||||
Expected:
|
||||
- New feature is created.
|
||||
- Original item is either removed or marked converted.
|
||||
|
||||
If not implemented:
|
||||
- This test is skipped.
|
||||
|
||||
## Manual Test Group 4 — Pulse Log
|
||||
|
||||
### Test 4.1: Add INTENT pulse
|
||||
|
||||
Steps:
|
||||
1. Open Pulse Log.
|
||||
2. Add pulse type INTENT.
|
||||
3. Link to a feature.
|
||||
4. Add message and confidence.
|
||||
|
||||
Expected:
|
||||
- Pulse appears in log.
|
||||
- Feature name is shown.
|
||||
- Pulse persists after refresh.
|
||||
|
||||
### Test 4.2: Add BLOCKER pulse without feature
|
||||
|
||||
Steps:
|
||||
1. Add pulse type BLOCKER.
|
||||
2. Do not link feature.
|
||||
3. Save.
|
||||
|
||||
Expected:
|
||||
- Pulse appears in log.
|
||||
- App does not require feature link.
|
||||
|
||||
### Test 4.3: Filter pulses
|
||||
|
||||
If filtering is implemented:
|
||||
|
||||
Steps:
|
||||
1. Add multiple pulse types.
|
||||
2. Filter by RESULT.
|
||||
3. Filter by feature.
|
||||
|
||||
Expected:
|
||||
- Correct pulses are shown.
|
||||
|
||||
## Manual Test Group 5 — Export
|
||||
|
||||
### Test 5.1: Export full JSON
|
||||
|
||||
Steps:
|
||||
1. Add project summary, features, parking items, and pulses.
|
||||
2. Export full JSON.
|
||||
3. Inspect file/content.
|
||||
|
||||
Expected:
|
||||
- JSON contains schema version.
|
||||
- JSON contains project.
|
||||
- JSON contains features.
|
||||
- JSON contains parking_lot.
|
||||
- JSON contains pulses.
|
||||
|
||||
### Test 5.2: Import JSON
|
||||
|
||||
Steps:
|
||||
1. Export JSON.
|
||||
2. Clear app or use different browser.
|
||||
3. Import JSON.
|
||||
|
||||
Expected:
|
||||
- Data is restored.
|
||||
- App does not duplicate IDs unexpectedly.
|
||||
|
||||
### Test 5.3: Export Pulse JSONL
|
||||
|
||||
Steps:
|
||||
1. Add several pulses.
|
||||
2. Export JSONL.
|
||||
|
||||
Expected:
|
||||
- Each line is valid JSON.
|
||||
- Each line represents one pulse event.
|
||||
|
||||
### Test 5.4: Export Markdown
|
||||
|
||||
Steps:
|
||||
1. Export Markdown package.
|
||||
2. Open `CLAUDE_CONTEXT.md`.
|
||||
|
||||
Expected:
|
||||
- Contains project summary.
|
||||
- Contains Now/Next/Later/Done features.
|
||||
- Contains Parking Lot.
|
||||
- Contains recent pulses.
|
||||
- Is useful as an AI coder handoff.
|
||||
|
||||
## Manual Test Group 6 — Mobile Usability
|
||||
|
||||
### Test 6.1: Phone layout
|
||||
|
||||
Steps:
|
||||
1. Open app in mobile-width browser.
|
||||
2. Navigate all views.
|
||||
3. Add feature.
|
||||
4. Add parked idea.
|
||||
5. Add pulse.
|
||||
|
||||
Expected:
|
||||
- UI is usable on phone.
|
||||
- No critical controls are inaccessible.
|
||||
|
||||
## Manual Test Group 7 — Scope Guard
|
||||
|
||||
### Test 7.1: Parking distracting idea
|
||||
|
||||
Scenario:
|
||||
User thinks of “real-time OpenClaw integration.”
|
||||
|
||||
Steps:
|
||||
1. Add it to Parking Lot.
|
||||
2. Mark risk as high/dangerous.
|
||||
3. Do not add it as active feature.
|
||||
|
||||
Expected:
|
||||
- Idea is captured.
|
||||
- Active v0.1 scope remains clean.
|
||||
|
||||
## Release Decision
|
||||
|
||||
v0.1 can ship when:
|
||||
- All required happy paths pass.
|
||||
- Data persists.
|
||||
- Export works.
|
||||
- App can manage BuildPulse itself.
|
||||
- No forbidden v0.1 scope items have been implemented.
|
||||
+211
@@ -0,0 +1,211 @@
|
||||
# BuildPulse UI Specification
|
||||
|
||||
## Design Goal
|
||||
|
||||
BuildPulse should feel like a calm cockpit, not an enterprise task manager.
|
||||
The user should quickly understand:
|
||||
- What is active now
|
||||
- What comes next
|
||||
- What has been parked
|
||||
- What happened recently
|
||||
- How to export context for AI work
|
||||
|
||||
## Main Navigation
|
||||
|
||||
v0.1 has four main views:
|
||||
1. Feature Plan
|
||||
2. Parking Lot
|
||||
3. Pulse Log
|
||||
4. Export
|
||||
|
||||
Optional small project summary area can appear in the header or dashboard area.
|
||||
|
||||
## Global Layout
|
||||
|
||||
Suggested layout:
|
||||
|
||||
```text
|
||||
------------------------------------------------
|
||||
BuildPulse Active Project: BuildPulse
|
||||
------------------------------------------------
|
||||
Feature Plan | Parking Lot | Pulse Log | Export
|
||||
------------------------------------------------
|
||||
Main content
|
||||
------------------------------------------------
|
||||
```
|
||||
|
||||
Mobile:
|
||||
- Navigation collapses into bottom tabs or simple top tabs.
|
||||
- Cards should stack vertically.
|
||||
- Editing can happen in modal, drawer, or full-screen panel.
|
||||
|
||||
## View 1: Feature Plan
|
||||
|
||||
Purpose:
|
||||
Show all feature cards grouped by current placement.
|
||||
|
||||
Columns:
|
||||
- Now
|
||||
- Next
|
||||
- Later
|
||||
- Done
|
||||
|
||||
Each card displays:
|
||||
- Title
|
||||
- Short description
|
||||
- Priority
|
||||
- Acceptance criteria count
|
||||
- Recent pulse indicator, optional
|
||||
|
||||
Actions:
|
||||
- Add feature
|
||||
- Edit feature
|
||||
- Delete feature
|
||||
- Move feature to another column
|
||||
- Add acceptance criteria
|
||||
- Add pulse for this feature
|
||||
|
||||
Feature detail panel fields:
|
||||
- Title
|
||||
- Description
|
||||
- Column
|
||||
- Priority
|
||||
- Status
|
||||
- Acceptance criteria
|
||||
- Scope notes
|
||||
|
||||
Empty state:
|
||||
No features yet. Add the first feature to define what you are building.
|
||||
|
||||
## View 2: Parking Lot
|
||||
|
||||
Purpose:
|
||||
Capture distracting ideas safely.
|
||||
|
||||
Each item displays:
|
||||
- Title
|
||||
- Description
|
||||
- Reason parked
|
||||
- Possible future placement
|
||||
- Risk level
|
||||
|
||||
Actions:
|
||||
- Add parked idea
|
||||
- Edit parked idea
|
||||
- Delete parked idea
|
||||
- Convert to feature
|
||||
- Add pulse event: `PARKED_IDEA`
|
||||
|
||||
Empty state:
|
||||
No parked ideas yet. This is where useful distractions go so they do not hijack the current build.
|
||||
|
||||
## View 3: Pulse Log
|
||||
|
||||
Purpose:
|
||||
Show what has happened over time.
|
||||
|
||||
Display:
|
||||
- Chronological event list, newest first by default
|
||||
- Filters:
|
||||
- Pulse type
|
||||
- Feature
|
||||
- Source/agent
|
||||
|
||||
Each pulse displays:
|
||||
- Timestamp
|
||||
- Pulse type
|
||||
- Feature title, if linked
|
||||
- Source/agent
|
||||
- Message
|
||||
- Confidence score
|
||||
- Evidence refs
|
||||
|
||||
Actions:
|
||||
- Add Pulse event
|
||||
- Edit Pulse event, optional
|
||||
- Delete Pulse event, optional for v0.1
|
||||
- Filter by feature
|
||||
- Filter by type
|
||||
|
||||
Add Pulse form fields:
|
||||
- Pulse type
|
||||
- Feature link, optional
|
||||
- Source/agent
|
||||
- Message
|
||||
- Confidence score
|
||||
- Evidence refs
|
||||
- Trace ID, optional
|
||||
|
||||
Empty state:
|
||||
No Pulse events yet. Add an `INTENT` or `DECISION` to start the project log.
|
||||
|
||||
## View 4: Export
|
||||
|
||||
Purpose:
|
||||
Create useful handoff context for AI coding agents.
|
||||
|
||||
Export options:
|
||||
1. Full JSON export
|
||||
2. Pulse JSONL export
|
||||
3. Markdown package export
|
||||
|
||||
Markdown package includes:
|
||||
- `PROJECT_SUMMARY.md`
|
||||
- `FEATURE_PLAN.md`
|
||||
- `PARKING_LOT.md`
|
||||
- `PULSE_LOG.md`
|
||||
- `CLAUDE_CONTEXT.md`
|
||||
|
||||
Actions:
|
||||
- Copy Markdown to clipboard
|
||||
- Download Markdown files, if practical
|
||||
- Download JSON
|
||||
- Download JSONL
|
||||
- Import JSON
|
||||
|
||||
Import behavior:
|
||||
- Validate schema
|
||||
- Show preview/confirmation, if practical
|
||||
- Handle invalid JSON gracefully
|
||||
- Avoid data loss where possible
|
||||
|
||||
## Project Summary Area
|
||||
|
||||
Project summary can be a compact editable panel.
|
||||
|
||||
Fields:
|
||||
- Project name
|
||||
- One-line pitch
|
||||
- Description
|
||||
- Current goal
|
||||
- Notes
|
||||
|
||||
This should not become a full project management screen in v0.1.
|
||||
|
||||
## Visual Style
|
||||
|
||||
Use:
|
||||
- Simple typography
|
||||
- Plenty of whitespace
|
||||
- Calm colors
|
||||
- Clear hierarchy
|
||||
- Rounded cards if desired
|
||||
- Low visual noise
|
||||
|
||||
Avoid:
|
||||
- Dense tables everywhere
|
||||
- Enterprise dashboards
|
||||
- Too many badges
|
||||
- Too many settings
|
||||
- Gamification
|
||||
- Overly flashy UI
|
||||
|
||||
## UX Priority
|
||||
|
||||
Most important UX actions:
|
||||
1. Add feature quickly.
|
||||
2. Park idea quickly.
|
||||
3. Add pulse quickly.
|
||||
4. Export context quickly.
|
||||
|
||||
The app should support quick capture without forcing perfect data entry.
|
||||
Reference in New Issue
Block a user