chore: create campaign mode branch, include sys spec, and update gitignore
This commit is contained in:
serversdwn
244
SYSTEMSPEC_v0.2.0.md
Normal file
244
SYSTEMSPEC_v0.2.0.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# Break It Down (BIT)
|
||||
|
||||
# SYSTEM SPECIFICATION
|
||||
|
||||
## Version: v0.2.0
|
||||
|
||||
## Feature Theme: Campaign Mode + Entropy Engine + Project Wizard
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 1. Overview
|
||||
|
||||
v0.2.0 introduces **Campaign Mode**, an operations layer on top of
|
||||
Break-It-Down's planning engine.
|
||||
|
||||
BIT remains the HQ planning system (tree + kanban). Campaign Mode is the
|
||||
execution layer focused on:
|
||||
|
||||
- Low-friction session starts
|
||||
- Visual progress (photo proof)
|
||||
- Entropy-based decay for recurring physical spaces
|
||||
- Gentle nudges to trigger action
|
||||
- A fast project-building Wizard
|
||||
|
||||
The goal is to reduce startup friction and help users act without
|
||||
overthinking.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 2. Core Architectural Principles
|
||||
|
||||
1. Existing planning functionality must remain unchanged for standard
|
||||
projects.
|
||||
2. Campaign functionality activates only when
|
||||
`project_mode == "entropy_space"`.
|
||||
3. Planning (HQ) and Execution (Campaign) are separate UI routes.
|
||||
4. Session start must require no pre-forms.
|
||||
5. Entropy simulation must feel like physics, not guilt.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 3. New Core Concepts
|
||||
|
||||
## 3.1 Project Modes
|
||||
|
||||
Add enum to projects:
|
||||
|
||||
- `standard` (default, existing behavior)
|
||||
- `entropy_space` (physical space / territory model)
|
||||
|
||||
Future modes may include: - `pipeline_chores` - `deep_work`
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 3.2 Campaign Types
|
||||
|
||||
Only meaningful when `project_mode == "entropy_space"`:
|
||||
|
||||
- `finite` --- one-off liberation (garage purge)
|
||||
- `background` --- ongoing maintenance (bathroom, kitchen)
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 3.3 Zones (v1 Implementation)
|
||||
|
||||
In `entropy_space` projects:
|
||||
|
||||
- Top-level tasks (`parent_task_id IS NULL`)
|
||||
- `is_zone = true`
|
||||
|
||||
No separate zones table in v0.2.0.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 3.4 Work Sessions
|
||||
|
||||
Generic sessions stored in backend. Campaign UI refers to them as
|
||||
"Strikes".
|
||||
|
||||
Session kinds:
|
||||
|
||||
- `strike`
|
||||
- `pomodoro` (future)
|
||||
- `run` (future)
|
||||
- `freeform`
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 4. Database Schema Changes
|
||||
|
||||
## 4.1 Projects Table Additions
|
||||
|
||||
project_mode TEXT NOT NULL DEFAULT 'standard'
|
||||
campaign_type TEXT NULL
|
||||
campaign_active BOOLEAN NOT NULL DEFAULT 0
|
||||
|
||||
nudge_enabled BOOLEAN NOT NULL DEFAULT 0
|
||||
nudge_window_start TEXT NULL
|
||||
nudge_window_end TEXT NULL
|
||||
nudge_min_interval_minutes INTEGER NULL
|
||||
nudge_max_per_day INTEGER NULL
|
||||
|
||||
photo_proof_enabled BOOLEAN NOT NULL DEFAULT 0
|
||||
default_session_kind TEXT NOT NULL DEFAULT 'freeform'
|
||||
default_session_minutes INTEGER NOT NULL DEFAULT 12
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 4.2 Tasks Table Additions (Zones Only)
|
||||
|
||||
is_zone BOOLEAN NOT NULL DEFAULT 0
|
||||
|
||||
stability_base INTEGER NULL
|
||||
decay_rate_per_day REAL NULL
|
||||
last_stability_update_at DATETIME NULL
|
||||
last_strike_at DATETIME NULL
|
||||
|
||||
zone_preset TEXT NULL
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 4.3 New Table: work_sessions
|
||||
|
||||
id INTEGER PRIMARY KEY
|
||||
project_id INTEGER NOT NULL
|
||||
task_id INTEGER NULL
|
||||
kind TEXT NOT NULL
|
||||
started_at DATETIME NOT NULL
|
||||
ended_at DATETIME NULL
|
||||
duration_seconds INTEGER NULL
|
||||
note TEXT NULL
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 4.4 New Table: session_photos
|
||||
|
||||
id INTEGER PRIMARY KEY
|
||||
session_id INTEGER NOT NULL
|
||||
phase TEXT NOT NULL -- 'before' or 'after'
|
||||
path TEXT NOT NULL
|
||||
taken_at DATETIME NOT NULL
|
||||
|
||||
Images stored in Docker volume under:
|
||||
|
||||
/data/photos/{project_id}/{session_id}/...
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 5. Entropy Engine (v1)
|
||||
|
||||
## 5.1 Stability Model
|
||||
|
||||
Fields used: - stability_base - last_stability_update_at -
|
||||
decay_rate_per_day
|
||||
|
||||
Derived:
|
||||
|
||||
days_elapsed = (now - last_stability_update_at)
|
||||
stability_now = max(0, stability_base - decay_rate_per_day * days_elapsed)
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 5.2 Strike Effect
|
||||
|
||||
On strike completion:
|
||||
|
||||
Option A (fixed):
|
||||
|
||||
boost = 20
|
||||
|
||||
Option B (duration-based):
|
||||
|
||||
boost = clamp(10, 35, round(duration_minutes * 1.5))
|
||||
|
||||
Update:
|
||||
|
||||
stability_base = min(100, stability_now + boost)
|
||||
last_stability_update_at = now
|
||||
last_strike_at = now
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 5.3 Stability Color Mapping
|
||||
|
||||
- 80--100 → green
|
||||
- 55--79 → yellow
|
||||
- 30--54 → orange
|
||||
- 0--29 → red
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 6. API Additions
|
||||
|
||||
## Campaign
|
||||
|
||||
POST /api/projects/{id}/launch_campaign
|
||||
GET /api/projects/{id}/zones
|
||||
|
||||
## Sessions
|
||||
|
||||
POST /api/sessions/start
|
||||
POST /api/sessions/{id}/stop
|
||||
GET /api/projects/{id}/sessions
|
||||
|
||||
## Photos
|
||||
|
||||
POST /api/sessions/{id}/photos
|
||||
GET /api/sessions/{id}/photos
|
||||
|
||||
## Wizard
|
||||
|
||||
POST /api/wizard/build_project
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 7. Frontend Routes
|
||||
|
||||
/projects
|
||||
/projects/:id
|
||||
/projects/:id/campaign
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 8. Build Phases
|
||||
|
||||
Phase 0: Core campaign + stability\
|
||||
Phase 1: Photo proof + compare slider\
|
||||
Phase 2: Nudges\
|
||||
Phase 3: Hex grid expansion
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# 9. Success Criteria
|
||||
|
||||
- Wizard creates entropy project in \<30 seconds\
|
||||
- Strike starts in 1 tap\
|
||||
- Stability increases after strike\
|
||||
- Stability decreases over time\
|
||||
- No regression in standard projects
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
**Break It Down v0.2.0**\
|
||||
Planning in HQ. Liberation on the front lines.
|
||||
Reference in New Issue
Block a user