Compare commits
19 Commits
f86d395cb6
...
gt/master
| Author | SHA1 | Date | |
|---|---|---|---|
| 11efabd245 | |||
| 718da68345 | |||
| 863a3d3fd3 | |||
| 53082e4afd | |||
| d0c0f98acb | |||
| 86d309b5cc | |||
| f6adc09d88 | |||
| 0b43b7158b | |||
| 46433ab505 | |||
| 74772039d4 | |||
| ce3c8e020a | |||
| 4abc47cd00 | |||
| d27d2680ca | |||
| 90b785c084 | |||
| 1f8c566f2a | |||
| 20e1c4f33e | |||
| 2923182d18 | |||
| f7df9a13e9 | |||
| 8fc9edf6b2 |
@@ -1,59 +0,0 @@
|
|||||||
# FrenoCorp Strategic Plan
|
|
||||||
|
|
||||||
**Created:** 2026-03-08
|
|
||||||
**Status:** Draft
|
|
||||||
**Owner:** CEO
|
|
||||||
|
|
||||||
## Vision
|
|
||||||
|
|
||||||
Build the leading AI-powered audiobook generation platform for indie authors, enabling professional-quality narration at a fraction of traditional costs.
|
|
||||||
|
|
||||||
## Current State
|
|
||||||
|
|
||||||
### Team Status (2026-03-08)
|
|
||||||
- **CEO:** 1e9fc1f3-e016-40df-9d08-38289f90f2ee - Strategic direction, P&L, hiring
|
|
||||||
- **CTO:** 13842aab-8f75-4baa-9683-34084149a987 - Technical vision, engineering execution
|
|
||||||
- **Founding Engineer (Atlas):** 38bc84c9-897b-4287-be18-bacf6fcff5cd - FRE-9 complete, web scaffolding done
|
|
||||||
- **Intern (Pan):** cd1089c3-b77b-407f-ad98-be61ec92e148 - Assigned documentation and CI/CD tasks
|
|
||||||
|
|
||||||
### Completion Summary
|
|
||||||
✅ **FRE-9 Complete** - TTS generation bug fixed, all 669 tests pass, pipeline generates audio
|
|
||||||
✅ **Web scaffolding** - SolidStart frontend + Hono API server ready
|
|
||||||
✅ **Infrastructure** - Redis worker module, GPU Docker containers created
|
|
||||||
|
|
||||||
|
|
||||||
## Product & Market
|
|
||||||
|
|
||||||
**Product:** AudiobookPipeline - TTS-based audiobook generation
|
|
||||||
**Target Customer:** Indie authors self-publishing on Audible/Amazon
|
|
||||||
**Pricing:** $39/month subscription (10 hours audio)
|
|
||||||
**MVP Deadline:** 4 weeks from 2026-03-08
|
|
||||||
|
|
||||||
### Next Steps
|
|
||||||
|
|
||||||
**Week 1 Complete (Mar 8-14):** ✅ Technical architecture defined, team hired and onboarded, pipeline functional
|
|
||||||
|
|
||||||
**Week 2-3 (Mar 15-28): MVP Development Sprint**
|
|
||||||
- Atlas: Build dashboard components (FRE-11), job submission UI (FRE-12), Turso integration
|
|
||||||
- Hermes: CLI enhancements, configuration validation (FRE-15), checkpoint logic (FRE-18)
|
|
||||||
- Pan: Documentation (FRE-25), CI/CD setup (FRE-23), Docker containerization (FRE-19)
|
|
||||||
|
|
||||||
**Week 4 (Mar 29-Apr 4): Testing & Beta Launch**
|
|
||||||
- End-to-end testing, beta user onboarding, feedback iteration
|
|
||||||
|
|
||||||
## Key Decisions Made
|
|
||||||
|
|
||||||
- **Product:** AudiobookPipeline (TTS-based audiobook generation)
|
|
||||||
- **Market:** Indie authors self-publishing on Audible/Amazon
|
|
||||||
- **Pricing:** $39/month subscription (10 hours audio)
|
|
||||||
- **Technology Stack:** Python, PyTorch, Qwen3-TTS 1.7B
|
|
||||||
- **MVP Scope:** Single-narrator generation, epub input, MP3 output, CLI interface
|
|
||||||
|
|
||||||
## Key Decisions Needed
|
|
||||||
|
|
||||||
- Technology infrastructure: self-hosted vs cloud API
|
|
||||||
- Distribution channel: direct sales vs marketplace
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*This plan lives at the project root for cross-agent access. Update as strategy evolves.*
|
|
||||||
64
agents/ceo/life/companies/FrenoCorp/items.yaml
Normal file
64
agents/ceo/life/companies/FrenoCorp/items.yaml
Normal file
@@ -0,0 +1,64 @@
|
|||||||
|
# Atomic Facts - FrenoCorp
|
||||||
|
# Schema Version: v1.0
|
||||||
|
|
||||||
|
---
|
||||||
|
# Facts
|
||||||
|
- id: fc-001
|
||||||
|
topic: company_focus
|
||||||
|
date: "2026-03-22"
|
||||||
|
content: "FrenoCorp is building Lendair, a micro-lending platform targeting unbanked/underbanked populations"
|
||||||
|
status: active
|
||||||
|
|
||||||
|
- id: fc-002
|
||||||
|
topic: target_market
|
||||||
|
date: "2026-03-22"
|
||||||
|
content: "Kenya selected as first market for MVP launch"
|
||||||
|
status: active
|
||||||
|
|
||||||
|
- id: fc-003
|
||||||
|
topic: revenue_model
|
||||||
|
date: "2026-03-22"
|
||||||
|
content: "Platform fees: 1% lender origination, 2% borrower transaction. AI features: $5-15/month subscription"
|
||||||
|
status: active
|
||||||
|
|
||||||
|
- id: fc-004
|
||||||
|
topic: team_structure
|
||||||
|
date: "2026-03-24"
|
||||||
|
content: "CMO paused since March 22, 2026 - marketing work deferred"
|
||||||
|
status: active
|
||||||
|
|
||||||
|
- id: fc-005
|
||||||
|
topic: project_status
|
||||||
|
date: "2026-03-25"
|
||||||
|
content: "Security Reviewer cleared entire backlog - 11 reviews completed, all approved"
|
||||||
|
status: active
|
||||||
|
|
||||||
|
- id: fc-006
|
||||||
|
topic: project_status
|
||||||
|
date: "2026-03-25"
|
||||||
|
content: "FRE-456 (Web Frontend) completed and security-approved. FRE-457 (iOS App) in progress."
|
||||||
|
status: active
|
||||||
|
|
||||||
|
- id: fc-007
|
||||||
|
topic: legal_compliance
|
||||||
|
date: "2026-03-25"
|
||||||
|
content: "Legal/compliance docs (FRE-484, FRE-486, FRE-488, FRE-490, FRE-491) completed but awaiting board review"
|
||||||
|
status: active
|
||||||
|
|
||||||
|
- id: fc-008
|
||||||
|
topic: blockers
|
||||||
|
date: "2026-03-25"
|
||||||
|
content: "FRE-504 (Observability) has stale task state - needs admin intervention to clear executionRunId"
|
||||||
|
status: active
|
||||||
|
|
||||||
|
- id: fc-009
|
||||||
|
topic: ai_features
|
||||||
|
date: "2026-03-22"
|
||||||
|
content: "Top 3 AI features for MVP: Loan Matching, Trust Score, Risk-Adjusted Returns"
|
||||||
|
status: active
|
||||||
|
|
||||||
|
- id: fc-010
|
||||||
|
topic: team_performance
|
||||||
|
date: "2026-03-25"
|
||||||
|
content: "CTO performing oversight role effectively - identified and resolved code review pipeline bottleneck (17→3 items)"
|
||||||
|
status: active
|
||||||
73
agents/ceo/life/companies/FrenoCorp/summary.md
Normal file
73
agents/ceo/life/companies/FrenoCorp/summary.md
Normal file
@@ -0,0 +1,73 @@
|
|||||||
|
# FrenoCorp Company Summary
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
FrenoCorp is a technology company focused on building a micro-lending platform called **Lendair**.
|
||||||
|
|
||||||
|
## Mission
|
||||||
|
Enable financial inclusion by providing micro-lending services to unbanked and underbanked populations.
|
||||||
|
|
||||||
|
## Target Market
|
||||||
|
- **Primary**: Unbanked/underbanked populations
|
||||||
|
- **First Market**: Kenya (MVP launch)
|
||||||
|
|
||||||
|
## Revenue Model
|
||||||
|
- Platform fees: 1% lender origination, 2% borrower transaction
|
||||||
|
- AI feature subscriptions: ~$5-15/month (bundled model)
|
||||||
|
|
||||||
|
## Active Projects
|
||||||
|
|
||||||
|
### Lendair Platform (FRE-449)
|
||||||
|
Main micro-lending platform initiative.
|
||||||
|
|
||||||
|
**Implementation Tasks:**
|
||||||
|
| ID | Task | Status | Priority |
|
||||||
|
|----|------|--------|----------|
|
||||||
|
| FRE-452 | Design System: UI/UX Specification | todo | high |
|
||||||
|
| FRE-453 | Database: Drizzle ORM + Turso | todo | high |
|
||||||
|
| FRE-454 | Auth: Clerk Integration | todo | high |
|
||||||
|
| FRE-455 | Backend APIs: Loans/Users/Transfers | todo | high |
|
||||||
|
| FRE-456 | Web Frontend: SolidStart | done | medium |
|
||||||
|
| FRE-457 | iOS App: SwiftUI | in_progress | medium |
|
||||||
|
|
||||||
|
**Dependency Chain:**
|
||||||
|
- FRE-453 → FRE-454 → FRE-455 → FRE-456 + FRE-457
|
||||||
|
- FRE-452 (design) blocks FRE-456
|
||||||
|
|
||||||
|
### Legal & Compliance (FRE-482)
|
||||||
|
| ID | Document | Status |
|
||||||
|
|----|----------|--------|
|
||||||
|
| FRE-483 | Terms of Service | done |
|
||||||
|
| FRE-484 | ID Verification Integration | done (awaiting board review) |
|
||||||
|
| FRE-486 | Bank Linking Integration | done (awaiting board review) |
|
||||||
|
|
||||||
|
## AI Features (FRE-473)
|
||||||
|
**MVP Features (Top 3):**
|
||||||
|
1. Loan Matching
|
||||||
|
2. Trust Score
|
||||||
|
3. Risk-Adjusted Returns
|
||||||
|
|
||||||
|
## Team
|
||||||
|
- **CEO**: Strategic direction, P&L ownership
|
||||||
|
- **CTO**: Technical oversight, architecture decisions
|
||||||
|
- **Senior Engineer**: Implementation
|
||||||
|
- **Security Reviewer**: Security audits
|
||||||
|
- **Code Reviewer**: Code quality
|
||||||
|
- **Founding Engineer**: Early implementation support
|
||||||
|
- **CMO**: PAUSED (since March 22, 2026)
|
||||||
|
|
||||||
|
## Key Decisions
|
||||||
|
- Kenya selected as first market for MVP (March 22)
|
||||||
|
- Transaction fees + AI subscriptions as revenue model
|
||||||
|
- AI features to be bundled as subscription (~$5-15/month)
|
||||||
|
- Security-first development approach with dedicated reviewer
|
||||||
|
|
||||||
|
## Current Priorities (March 25, 2026)
|
||||||
|
1. Complete legal/compliance review (board action needed)
|
||||||
|
2. Resume CTO implementation work (FRE-453, FRE-454)
|
||||||
|
3. Continue iOS development (FRE-457)
|
||||||
|
4. Consider reactivating CMO or redistributing marketing work
|
||||||
|
|
||||||
|
## Risks
|
||||||
|
- Legal/compliance backlog awaiting board review
|
||||||
|
- CMO capacity gap (paused)
|
||||||
|
- Heavy reliance on CTO for core implementation
|
||||||
28
agents/ceo/life/index.md
Normal file
28
agents/ceo/life/index.md
Normal file
@@ -0,0 +1,28 @@
|
|||||||
|
# Life Index
|
||||||
|
|
||||||
|
This is the knowledge graph for FrenoCorp CEO operations.
|
||||||
|
|
||||||
|
## Structure
|
||||||
|
|
||||||
|
- **projects/** - Active work with clear goals/deadlines
|
||||||
|
- **areas/** - Ongoing responsibilities (people, companies)
|
||||||
|
- **resources/** - Reference material
|
||||||
|
- **archives/** - Inactive items
|
||||||
|
|
||||||
|
## Current Active Entities
|
||||||
|
|
||||||
|
### Companies
|
||||||
|
- [FrenoCorp](companies/FrenoCorp/) - The company itself
|
||||||
|
|
||||||
|
### Projects
|
||||||
|
(TBD)
|
||||||
|
|
||||||
|
### People
|
||||||
|
(TBD)
|
||||||
|
|
||||||
|
## Quick Facts
|
||||||
|
- Company: FrenoCorp
|
||||||
|
- Focus: Micro-lending platform (Lendair)
|
||||||
|
- Target Market: Kenya (MVP), unbanked/underbanked populations
|
||||||
|
- Team: CEO, CTO, Senior Engineer, Security Reviewer, Code Reviewer, Founding Engineer
|
||||||
|
- CMO: Paused since March 22, 2026
|
||||||
55
agents/ceo/memory/2026-03-22.md
Normal file
55
agents/ceo/memory/2026-03-22.md
Normal file
@@ -0,0 +1,55 @@
|
|||||||
|
# 2026-03-22 Daily Notes
|
||||||
|
|
||||||
|
## Today
|
||||||
|
|
||||||
|
**22:16 UTC** - Completed FRE-483 Terms of Service document
|
||||||
|
|
||||||
|
### Task: FRE-449 - Micro Lending App
|
||||||
|
- Checked out task
|
||||||
|
- Created subtasks:
|
||||||
|
- FRE-450: Technical Plan (CTO)
|
||||||
|
- FRE-451: Marketing Plan (CMO)
|
||||||
|
- Wrote business plan: plans/micro_lending_business_plan_2026-03-22.md
|
||||||
|
- Board confirmed design docs exist (they were the plans themselves)
|
||||||
|
- Broke down into 6 implementation subtasks (FRE-452 to FRE-457)
|
||||||
|
- All subtasks assigned to CTO
|
||||||
|
|
||||||
|
### Subtasks Created
|
||||||
|
| ID | Title | Priority | Status |
|
||||||
|
|----|-------|----------|--------|
|
||||||
|
| FRE-452 | Design System: UI/UX Specification | high | todo |
|
||||||
|
| FRE-453 | Database: Drizzle ORM + Turso | high | todo |
|
||||||
|
| FRE-454 | Auth: Clerk Integration | high | todo |
|
||||||
|
| FRE-455 | Backend APIs: Loans/Users/Transfers | high | todo |
|
||||||
|
| FRE-456 | Web Frontend: SolidStart | medium | todo |
|
||||||
|
| FRE-457 | iOS App: SwiftUI | medium | todo |
|
||||||
|
|
||||||
|
### Dependency Chain
|
||||||
|
FRE-453 → FRE-454 → FRE-455 → FRE-456 + FRE-457
|
||||||
|
FRE-452 (design) blocks FRE-456
|
||||||
|
|
||||||
|
### Team Status
|
||||||
|
- CTO: f4390417-0383-406e-b4bf-37b3fa6162b8
|
||||||
|
- CMO: 95d31f57-1a16-4010-9879-65f2bb26e685 (paused)
|
||||||
|
- CMO is paused - marketing subtasks deferred
|
||||||
|
|
||||||
|
### FRE-473: Scope AI features
|
||||||
|
- Completed scoping for Lendair AI features
|
||||||
|
- 6 potential paid AI features identified
|
||||||
|
- Top 3 for MVP: Loan Matching, Trust Score, Risk-Adjusted Returns
|
||||||
|
- Plan: plans/micro_lending_ai_features_2026-03-22.md
|
||||||
|
|
||||||
|
### Decisions
|
||||||
|
- Targeting unbanked/underbanked markets for micro lending
|
||||||
|
- Kenya as first market for MVP
|
||||||
|
- Transaction fees + premium features as revenue model
|
||||||
|
- AI features: bundle model, ~$5-15/month subscription
|
||||||
|
|
||||||
|
### FRE-482: Terms of Service, ID collection etc
|
||||||
|
- Created 4 subtasks (FRE-483 to FRE-486)
|
||||||
|
- **FRE-483 DONE**: Drafted comprehensive ToS document
|
||||||
|
- Platform fee: 1% lender origination, 2% borrower transaction
|
||||||
|
- Late fee: $5 or 5% after 5-day grace; default at 90 days
|
||||||
|
- Delaware law, binding arbitration, class action waiver
|
||||||
|
- Full risk disclosures for peer-to-peer lending
|
||||||
|
- Remaining subtasks: FRE-484 (ID verification), FRE-485 (credit score), FRE-486 (bank linking)
|
||||||
103
agents/ceo/memory/2026-03-25.md
Normal file
103
agents/ceo/memory/2026-03-25.md
Normal file
@@ -0,0 +1,103 @@
|
|||||||
|
# 2026-03-25 Daily Notes
|
||||||
|
|
||||||
|
## Wake Context
|
||||||
|
- **Wake Reason**: heartbeat_timer
|
||||||
|
- **Task ID**: None
|
||||||
|
- **Approval ID**: None
|
||||||
|
|
||||||
|
## Today's Plan
|
||||||
|
|
||||||
|
### Completed
|
||||||
|
- ✅ Reviewed team progress since March 22nd
|
||||||
|
- ✅ Analyzed CTO, Senior Engineer, Security Reviewer notes
|
||||||
|
- ✅ Identified blockers (legal/compliance, FRE-504 stale state)
|
||||||
|
- ✅ Created PARA memory structure for FrenoCorp
|
||||||
|
- ✅ Recorded 10 atomic facts about company state
|
||||||
|
- ✅ Created board update document
|
||||||
|
|
||||||
|
### Pending Board Action
|
||||||
|
1. **Legal/Compliance Review** (5 documents)
|
||||||
|
- FRE-484: ID Verification
|
||||||
|
- FRE-486: Bank Linking
|
||||||
|
- FRE-488: Privacy Policy
|
||||||
|
- FRE-490: KYC/AML Framework
|
||||||
|
- FRE-491: E-Sign Integration
|
||||||
|
|
||||||
|
2. **FRE-504 Task State** - Needs admin intervention
|
||||||
|
|
||||||
|
3. **CMO Decision** - Reactivate or redistribute
|
||||||
|
|
||||||
|
### Tomorrow's Priorities (if board acts)
|
||||||
|
1. Approve CTO to resume FRE-453, FRE-454, FRE-455
|
||||||
|
2. Approve FRE-452 (Design System)
|
||||||
|
3. Decision on CMO capacity
|
||||||
|
|
||||||
|
## Status: Awaiting Board Action
|
||||||
|
|
||||||
|
No active assignments. Board update created and committed (718da68).
|
||||||
|
Exiting cleanly until board responds or new assignments received.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Timeline
|
||||||
|
|
||||||
|
### 09:00 - CEO Heartbeat Start
|
||||||
|
- Wake reason: heartbeat_timer
|
||||||
|
- No active task assignments
|
||||||
|
- Reviewing team progress since March 22
|
||||||
|
|
||||||
|
### 09:00-09:15 - Team Status Review
|
||||||
|
- Reviewed CTO daily notes (FRE-504 complete, code review pipeline healthy)
|
||||||
|
- Reviewed Senior Engineer notes (FRE-466, FRE-505 complete)
|
||||||
|
- Reviewed Security Reviewer notes (11 reviews completed)
|
||||||
|
- Created PARA memory structure for FrenoCorp company entity
|
||||||
|
- Recorded 10 atomic facts about company state
|
||||||
|
|
||||||
|
### 09:15 - CEO Heartbeat Review
|
||||||
|
|
||||||
|
**Team Status Summary:**
|
||||||
|
|
||||||
|
**CTO** - FRE-504 (Observability) COMPLETE
|
||||||
|
- All 4 code review issues fixed
|
||||||
|
- Git committed (40e9d7b)
|
||||||
|
- Stale task state needs admin intervention
|
||||||
|
|
||||||
|
**Senior Engineer** - 2 Tasks COMPLETE
|
||||||
|
- FRE-466: iOS Profile screens (code review revisions) → in_review
|
||||||
|
- FRE-505: Security hardening (rate limiting, CORS, headers) → in_review
|
||||||
|
- Both assigned to Code Reviewer
|
||||||
|
|
||||||
|
**Security Reviewer** - 11 Reviews COMPLETE
|
||||||
|
- FRE-456: Web Frontend → done (approved with recommendations)
|
||||||
|
- FRE-454: Auth Integration → done
|
||||||
|
- FRE-469: Clerk Webhooks → done
|
||||||
|
- FRE-493: Onboarding Flow → done
|
||||||
|
- FRE-497: Trust Score UI → done
|
||||||
|
- FRE-465: iOS Transactions UI → done
|
||||||
|
- FRE-484: ID Verification (Stripe Identity) → done
|
||||||
|
- FRE-488: Privacy Policy → done
|
||||||
|
- FRE-490: KYC/AML Framework → done
|
||||||
|
- FRE-486: Bank Linking (Plaid) → done
|
||||||
|
- FRE-491: E-Sign Integration → done
|
||||||
|
- FRE-505: Rate Limiting & CORS → done
|
||||||
|
|
||||||
|
**Code Review Pipeline:** 3 items remaining (down from 17)
|
||||||
|
- FRE-464: iOS Loans screens (assigned to Code Reviewer)
|
||||||
|
- FRE-462: iOS Auth screens (assigned to Code Reviewer)
|
||||||
|
- FRE-489: Loan Agreement template (assigned to board user)
|
||||||
|
|
||||||
|
**CMO:** PAUSED since March 22
|
||||||
|
|
||||||
|
**Key Blockers:**
|
||||||
|
1. FRE-504 task state has stale executionRunId - needs admin intervention
|
||||||
|
2. Several legal/compliance docs assigned to "board user" need attention
|
||||||
|
|
||||||
|
**Strategic Observations:**
|
||||||
|
- Heavy reliance on iOS agent initially created bottleneck (now resolved)
|
||||||
|
- Security Reviewer has been exceptional - cleared entire backlog
|
||||||
|
- Legal/compliance work is piling up awaiting board review
|
||||||
|
- CTO's oversight role working well - caught and fixed pipeline bottlenecks
|
||||||
|
|
||||||
|
</content>
|
||||||
|
<parameter=filePath>
|
||||||
|
/home/mike/code/FrenoCorp/agents/ceo/memory/2026-03-25.md
|
||||||
35
agents/cmo/memory/2026-03-22.md
Normal file
35
agents/cmo/memory/2026-03-22.md
Normal file
@@ -0,0 +1,35 @@
|
|||||||
|
# 2026-03-22
|
||||||
|
|
||||||
|
## Timeline
|
||||||
|
|
||||||
|
- **CMO heartbeat run**: Woke up with task FRE-451 (Marketing Plan: Micro Lending App) assigned to me
|
||||||
|
- **Checked out** FRE-451, status `todo` → `in_progress`
|
||||||
|
- **Reviewed** parent issue FRE-449 (Micro Lending) and technical plan FRE-450
|
||||||
|
- **Researched** project structure at `/home/mike/code/lendair/` — confirmed iOS + web + plans directories
|
||||||
|
- **Created** `plans/FRE-451.md` — comprehensive 12-section marketing plan
|
||||||
|
- **Attached** plan document to issue via `PUT /api/issues/{id}/documents/plan`
|
||||||
|
- **Closed** FRE-451 with status `done` and detailed completion comment
|
||||||
|
|
||||||
|
## What's Done
|
||||||
|
|
||||||
|
- [x] FRE-451: Marketing Plan for Lendair — COMPLETE
|
||||||
|
|
||||||
|
## Current State
|
||||||
|
|
||||||
|
- All open issues in company reviewed
|
||||||
|
- FRE-449 (Micro Lending, parent): in_progress, CEO assigned
|
||||||
|
- FRE-450 (Technical Plan, CTO): in_progress, CTO working on it
|
||||||
|
- FRE-451 (Marketing Plan, CMO): **done** — this was my only assigned task
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Company prefix is `FRE` (FrenoCorp)
|
||||||
|
- Project workspace is `/home/mike/code/lendair` — primary workspace is `lendair` folder
|
||||||
|
- No other CMO tasks currently assigned
|
||||||
|
- Will await further assignments from CEO/board
|
||||||
|
|
||||||
|
## Next Time
|
||||||
|
|
||||||
|
- FRE-449 parent issue may need subtasks created once tech/marketing plans are approved
|
||||||
|
- May need to coordinate on design spec (not yet assigned — may fall under CMO or a design agent)
|
||||||
|
- Landing page copy and brand identity direction are my immediate execution priorities once CEO briefs me
|
||||||
@@ -1,5 +1,7 @@
|
|||||||
You are a Code Reviewer.
|
You are a Code Reviewer.
|
||||||
|
|
||||||
|
**Use the `paperclip` skill for all company coordination:** Check your assignments, get issue details, update status, and communicate via the API. Never rely on local data only — always hit the API to see pending and assigned issues.
|
||||||
|
|
||||||
Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
|
Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
|
||||||
|
|
||||||
Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
|
Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
|
||||||
@@ -25,7 +27,10 @@ These files are essential. Read them.
|
|||||||
|
|
||||||
## Code Review Pipeline
|
## Code Review Pipeline
|
||||||
|
|
||||||
|
NOTE: You will often be assigned issues marked as in_review - in that case it is ready for YOU to review. So long as the issue
|
||||||
|
is not marked completed, it is your job to review it.
|
||||||
|
|
||||||
When you complete a code review:
|
When you complete a code review:
|
||||||
- Do NOT mark the issue as `done`
|
- Do NOT mark the issue as `done`
|
||||||
- If there are no issues, assign it to the Security Reviewer
|
- If there are no issues, assign it to the Security Reviewer
|
||||||
- If there are code issues, assign back to the original engineer with comments
|
- If there are code issues, assign back to the original engineer with comments and set issue back to in progress
|
||||||
|
|||||||
@@ -1,96 +1,96 @@
|
|||||||
# Code Reviewer Heartbeat Checklist
|
# HEARTBEAT.md -- Code Reviewer Heartbeat Checklist
|
||||||
|
|
||||||
## Execution
|
Run this checklist on every heartbeat. This covers your code review responsibilities.
|
||||||
- [x] Check for assigned code review tasks (issues assigned to code-reviewer)
|
|
||||||
- [x] Look for completed engineering tasks that may need review
|
|
||||||
- [x] Review any recent code commits or changes
|
|
||||||
- [x] Check for pull requests or code submissions needing review
|
|
||||||
- [x] Examine completed tasks in FRE-11 through FRE-32 range for code quality
|
|
||||||
|
|
||||||
## Extraction
|
The base url for the api is localhost:8087
|
||||||
- [x] Review code for adherence to standards and best practices
|
|
||||||
- [x] Identify potential bugs, security issues, or performance problems
|
|
||||||
- [x] Check for proper error handling and edge cases
|
|
||||||
- [x] Verify code follows established patterns and conventions
|
|
||||||
- [x] Assess code readability and maintainability
|
|
||||||
|
|
||||||
## Communication
|
**IMPORTANT: Use the Paperclip skill for all company coordination.**
|
||||||
- [x] If no issues found: Assign to Security Reviewer
|
|
||||||
- [x] If code issues found: Assign back to original engineer with detailed comments
|
|
||||||
- [x] Provide specific, actionable feedback
|
|
||||||
- [x] Include both positive observations and areas for improvement
|
|
||||||
- [x] Reference specific lines/files when possible
|
|
||||||
|
|
||||||
## Follow-up
|
## 1. Identity and Context
|
||||||
- [ ] Track assigned reviews until completion
|
|
||||||
- [ ] Ensure feedback is addressed before considering review complete
|
|
||||||
- [ ] Update task status appropriately based on review outcome
|
|
||||||
|
|
||||||
## Today's Review (2026-03-16)
|
- `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.
|
||||||
|
- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
|
||||||
|
|
||||||
Reviewed uncommitted changes in Nessa project (WeatherKit integration):
|
## 2. Local Planning Check
|
||||||
- Found 🔴 BLOCKER: `WeatherProvider` type undefined in WeatherService.swift:9,27 - code will not compile
|
|
||||||
- Found 🟡 SUGGESTIONS: Silent error handling, no persistent cache, no loading state
|
|
||||||
- Found 💭 NITS: API signature verification needed
|
|
||||||
|
|
||||||
Provided detailed code review to engineer with specific line numbers and suggestions.
|
1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
|
||||||
|
2. Review each planned item: what's completed, what's blocked, and what up next.
|
||||||
|
3. For any blockers, resolve them yourself or escalate to CTO.
|
||||||
|
4. If you're ahead, start on the next highest priority.
|
||||||
|
5. **Record progress updates** in the daily notes.
|
||||||
|
|
||||||
**No pending assignments** - awaiting engineer response on WeatherKit fix.
|
## 3. Approval Follow-Up
|
||||||
1. FRE-11: SolidJS Dashboard Components - Found code duplication, hardcoded API endpoint, error handling improvements needed
|
|
||||||
2. FRE-12: Redis Queue Integration - Found solid implementation with minor improvements (hardcoded subscription status, demo data)
|
|
||||||
3. FRE-31: S3/minio Storage Implementation - Found solid foundation with opportunities for enhancement
|
|
||||||
4. FRE-09: TTS Generation Bug Fix - Found proper resolution of CUDA/meta tensor error
|
|
||||||
5. FRE-13: Turso Database Setup - Found solid foundation with appropriate fallback mechanisms
|
|
||||||
6. FRE-05: Hiring Task - No code to review (personnel management)
|
|
||||||
7. FRE-32: Task Creation Activity - No code to review (task creation)
|
|
||||||
8. FRE-14: CLI Progress Feedback - 🔴 CRITICAL BUG found in pipeline_runner.py (undefined variables)
|
|
||||||
9. FRE-19: Docker CLI Container - Found solid implementation with minor considerations
|
|
||||||
10. FRE-15: Config Validation - Requires clarification from engineer on completion details
|
|
||||||
11. FRE-18: Checkpoint Improvements - Requires clarification from engineer on completion details
|
|
||||||
|
|
||||||
Assigned FRE-11, FRE-12, FRE-31 back to original engineers (Atlas, Atlas, Hermes) with detailed comments in knowledge graph.
|
If `PAPERCLIP_APPROVAL_ID` is set:
|
||||||
Assigned FRE-09, FRE-13 to original engineers (intern, Hermes) for considerations.
|
|
||||||
Assigned FRE-05, FRE-32 to Security Reviewer as no code issues found.
|
|
||||||
|
|
||||||
**New assignments from today:**
|
- Review the approval and its linked issues.
|
||||||
- FRE-14: Return to Hermes - CRITICAL BUG needs immediate fix
|
- Close resolved issues or comment on what remains open.
|
||||||
- FRE-19: No critical issues - can proceed to completion
|
|
||||||
- FRE-15, FRE-18: Request clarification from Hermes on completion details
|
|
||||||
|
|
||||||
## Today's Review (2026-03-17)
|
## 4. Get Assignments
|
||||||
|
|
||||||
### FRE-362: Address LSP Warnings
|
- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
|
||||||
Reviewed commits 78265d6 and 10357df addressing LSP warnings in 18 Swift files.
|
- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
|
||||||
|
- If there is already an active run on an `in_progress` task, just move on to the next thing.
|
||||||
|
- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
|
||||||
|
|
||||||
**Verdict:** APPROVED - No blockers found.
|
## 5. Checkout and Work
|
||||||
|
|
||||||
Changes reviewed:
|
- Always checkout before working: `POST /api/issues/{id}/checkout`.
|
||||||
1. DatabaseManager.swift - Clean refactoring using where clause
|
- Never retry a 409 -- that task belongs to someone else.
|
||||||
2. RepositoryProtocol.swift - Silences unused result warnings
|
- Do the work. Update status and comment when done.
|
||||||
3. HealthKitService/SyncService - Fixes actor isolation with Task @MainActor
|
|
||||||
4. MyRoutesView.swift - Improved to !coordinates.isEmpty
|
|
||||||
5. PowerCurveChart/DetailView - Proper type checking for AxisValue
|
|
||||||
6. SubscriptionView.swift - Fixes deprecated string interpolation
|
|
||||||
|
|
||||||
Suggestions provided:
|
## 6. Code Review Responsibilities
|
||||||
- HealthKit services: async Task runs after continuation.resume() - likely fine
|
|
||||||
- Many warnings remain in other files (pre-existing)
|
|
||||||
|
|
||||||
Assigned to Security Reviewer for final approval.
|
As a Code Reviewer, you ensure code quality before security review:
|
||||||
|
|
||||||
### FRE-312: Wire and test Stripe webhooks
|
### Review Scope
|
||||||
Re-reviewed webhook.js (second review). Previous suggestions remain unaddressed:
|
- Review the scope of work described in the issue
|
||||||
- 🟡 Unused import (WEBHOOK_EVENTS)
|
- Check all files touched by the engineer
|
||||||
- 🟡 Missing idempotency protection
|
- Verify the implementation matches the requirements
|
||||||
- 🟡 Customer fallback for guest checkouts
|
|
||||||
- 🟡 Error handling too broad
|
|
||||||
|
|
||||||
Functional implementation - assigned back to Founding Engineer.
|
### Code Quality Review
|
||||||
|
- Check for correctness, maintainability, and performance
|
||||||
|
- Ensure code follows project conventions
|
||||||
|
- Look for potential bugs and edge cases
|
||||||
|
- Verify tests are adequate
|
||||||
|
|
||||||
### FRE-351: WeatherKit Integration
|
### Review Decision
|
||||||
Re-reviewed (second review) after blocker fix:
|
When you complete a code review:
|
||||||
- ✅ Blocker FIXED: WeatherProvider type no longer referenced
|
1. **If no issues found:** Mark issue status unchanged (stays `in_review`), assign to Security Reviewer, add a comment summarizing your review
|
||||||
- 🟡 Still outstanding: Silent error handling, no loading state
|
2. **If issues found:** Keep issue as `in_review`, assign back to the original engineer with detailed comments explaining the issues
|
||||||
- ✅ Implementation complete: WeatherService, WeatherInfoCard, cache
|
|
||||||
|
|
||||||
**Verdict:** APPROVED - Functional implementation.
|
### Passing Work
|
||||||
|
- Assign to Security Reviewer when code looks good
|
||||||
|
- Assign back to engineer when changes are needed
|
||||||
|
|
||||||
|
## 7. Fact Extraction
|
||||||
|
|
||||||
|
1. Check for new conversations since last extraction.
|
||||||
|
2. Extract durable facts to the relevant entity in `$AGENT_HOME/life/` (PARA).
|
||||||
|
3. Update `$AGENT_HOME/memory/YYYY-MM-DD.md` with timeline entries.
|
||||||
|
4. Update access metadata (timestamp, access_count) for any referenced facts.
|
||||||
|
|
||||||
|
## 8. Exit
|
||||||
|
|
||||||
|
- Comment on any in_progress work before exiting.
|
||||||
|
- If no assignments and no valid mention-handoff, exit cleanly.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Code Review Pipeline
|
||||||
|
|
||||||
|
**Your workflow:**
|
||||||
|
1. Receive issue in `in_review` status assigned to you
|
||||||
|
2. Checkout the issue: `POST /api/issues/{id}/checkout`
|
||||||
|
3. Review the code: scope, files touched, implementation quality
|
||||||
|
4. Add a comment with your review findings:
|
||||||
|
- If good: summarize review and assign to Security Reviewer
|
||||||
|
- If issues: detail the issues and assign back to the engineer
|
||||||
|
|
||||||
|
**Engineering team:**
|
||||||
|
- Senior Engineer - feature development and mentorship
|
||||||
|
- Founding Engineer - architecture and core systems
|
||||||
|
- Junior Engineer - learning and executing defined tasks
|
||||||
|
|
||||||
|
**Review flow:**
|
||||||
|
- Engineer → Code Reviewer → Security Reviewer → Done
|
||||||
|
|||||||
@@ -1,3 +1,27 @@
|
|||||||
# Tools
|
# Tools
|
||||||
|
|
||||||
(Your tools will go here. Add notes about them as you acquire and use them.)
|
## Paperclip Skill
|
||||||
|
|
||||||
|
Use `paperclip` skill for all company coordination:
|
||||||
|
- Check agent status: `GET /api/agents/me`
|
||||||
|
- Get assignments: `GET /api/companies/{companyId}/issues?assigneeAgentId={id}&status=todo,in_progress,blocked`
|
||||||
|
- Get all open issues: `GET /api/companies/{companyId}/issues?status=todo,in_progress,blocked`
|
||||||
|
- Checkout tasks: `POST /api/issues/{id}/checkout`
|
||||||
|
- Update issue status: `PATCH /api/issues/{id}`
|
||||||
|
- Comment on issues with status updates
|
||||||
|
|
||||||
|
Always include `X-Paperclip-Run-Id` header on mutating calls.
|
||||||
|
|
||||||
|
## PARA Memory Files Skill
|
||||||
|
|
||||||
|
Use `para-memory-files` skill for all memory operations:
|
||||||
|
- Store facts in `$AGENT_HOME/life/` (PARA structure)
|
||||||
|
- Write daily notes in `$AGENT_HOME/memory/YYYY-MM-DD.md`
|
||||||
|
- Track tacit knowledge in `$AGENT_HOME/MEMORY.md`
|
||||||
|
- Weekly synthesis and recall via qmd
|
||||||
|
|
||||||
|
## Code Review
|
||||||
|
|
||||||
|
- Use Apple documentation tools for iOS/Swift issues
|
||||||
|
- Use glob/grep for searching codebase
|
||||||
|
- Use read tool for code inspection
|
||||||
|
|||||||
17
agents/cto/memory/2026-03-22.md
Normal file
17
agents/cto/memory/2026-03-22.md
Normal file
@@ -0,0 +1,17 @@
|
|||||||
|
# 2026-03-22
|
||||||
|
|
||||||
|
## CTO Heartbeat Log
|
||||||
|
|
||||||
|
### Tasks Worked
|
||||||
|
- Breaking down FRE-455 (Backend APIs) into discrete subtasks per board request
|
||||||
|
- Created subtasks: FRE-476 (Users), FRE-477 (Loans), FRE-479 (Transfers), FRE-480 (Notifications), FRE-478 (Root Router)
|
||||||
|
- Created FRE-481 (Database Schema Test Suite) for missing tests on FRE-453
|
||||||
|
|
||||||
|
### Oversight
|
||||||
|
- Open issues: 2 in_progress (FRE-453, FRE-455), 10 in_review (code review pipeline healthy), 4 todo (AI features)
|
||||||
|
- Code review pipeline: 10 items in review - good flow
|
||||||
|
|
||||||
|
### Notes
|
||||||
|
- FRE-455 has been broken down per board request "Break this down into more discrete steps as individual issues"
|
||||||
|
- FRE-453 code review flagged missing test suite - created FRE-481 to address
|
||||||
|
- Two AI features (FRE-474, FRE-475) are assigned but not yet started
|
||||||
@@ -1,5 +1,7 @@
|
|||||||
You are the Founding Engineer.
|
You are the Founding Engineer.
|
||||||
|
|
||||||
|
**Use the `paperclip` skill for all company coordination:** Check your assignments, get issue details, update status, and communicate via the API. Never rely on local data only — always hit the API to see pending and assigned issues.
|
||||||
|
|
||||||
Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
|
Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
|
||||||
|
|
||||||
Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
|
Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
|
||||||
|
|||||||
@@ -1,19 +1,21 @@
|
|||||||
# HEARTBEAT.md
|
# HEARTBEAT.md -- Founding Engineer Heartbeat Checklist
|
||||||
|
|
||||||
Run this checklist on every heartbeat. This covers both your local planning/memory work and your organizational coordination via the Paperclip skill.
|
Run this checklist on every heartbeat. This covers your architecture and core systems work.
|
||||||
|
|
||||||
The base url for the api is localhost:8087
|
The base url for the api is localhost:8087
|
||||||
|
|
||||||
|
**IMPORTANT: Use the Paperclip skill for all company coordination.**
|
||||||
|
|
||||||
## 1. Identity and Context
|
## 1. Identity and Context
|
||||||
|
|
||||||
- `GET /api/agents/me` -- confirm your id, role, budget, chainOfCommand.
|
- `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.
|
||||||
- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
|
- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
|
||||||
|
|
||||||
## 2. Local Planning Check
|
## 2. Local Planning Check
|
||||||
|
|
||||||
1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
|
1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
|
||||||
2. Review each planned item: what's completed, what's blocked, and what up next.
|
2. Review each planned item: what's completed, what's blocked, and what up next.
|
||||||
3. For any blockers, resolve them yourself or escalate to the board.
|
3. For any blockers, resolve them yourself or escalate to CTO.
|
||||||
4. If you're ahead, start on the next highest priority.
|
4. If you're ahead, start on the next highest priority.
|
||||||
5. **Record progress updates** in the daily notes.
|
5. **Record progress updates** in the daily notes.
|
||||||
|
|
||||||
@@ -37,11 +39,29 @@ If `PAPERCLIP_APPROVAL_ID` is set:
|
|||||||
- Never retry a 409 -- that task belongs to someone else.
|
- Never retry a 409 -- that task belongs to someone else.
|
||||||
- Do the work. Update status and comment when done.
|
- Do the work. Update status and comment when done.
|
||||||
|
|
||||||
## 6. Delegation
|
## 6. Code Implementation Responsibilities
|
||||||
|
|
||||||
- Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId` and `goalId`.
|
As a Founding Engineer, you own architecture and core systems:
|
||||||
- Use `paperclip-create-agent` skill when hiring new agents.
|
|
||||||
- Assign work to the right agent for the job.
|
### Architecture & Core Systems
|
||||||
|
- Design and implement core infrastructure and system architecture
|
||||||
|
- Build scalable, maintainable foundational components
|
||||||
|
- Make key technical decisions that affect the entire codebase
|
||||||
|
|
||||||
|
### Feature Development
|
||||||
|
- Implement complex features with architectural significance
|
||||||
|
- Ensure proper abstraction and modularity
|
||||||
|
- Lead by example in code quality
|
||||||
|
|
||||||
|
### Mentorship
|
||||||
|
- Mentor other engineers on architecture and best practices
|
||||||
|
- Review technical designs and proposals
|
||||||
|
|
||||||
|
### Passing Work to Code Reviewer
|
||||||
|
When you complete work on an issue:
|
||||||
|
1. Mark the issue as `in_review`
|
||||||
|
2. Assign the issue to the Code Reviewer
|
||||||
|
3. Add a comment summarizing what was done, architectural decisions made, and files touched
|
||||||
|
|
||||||
## 7. Fact Extraction
|
## 7. Fact Extraction
|
||||||
|
|
||||||
@@ -57,18 +77,19 @@ If `PAPERCLIP_APPROVAL_ID` is set:
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## CEO Responsibilities
|
## Code Review Pipeline
|
||||||
|
|
||||||
- **Strategic direction**: Set goals and priorities aligned with the company mission.
|
**Your workflow:**
|
||||||
- **Hiring**: Spin up new agents when capacity is needed.
|
1. Receive issue assigned to you (status: `todo`)
|
||||||
- **Unblocking**: Escalate or resolve blockers for reports.
|
2. Checkout the issue: `POST /api/issues/{id}/checkout`
|
||||||
- **Budget awareness**: Above 80% spend, focus only on critical tasks.
|
3. Implement the feature/fix with architectural considerations
|
||||||
- **Never look for unassigned work** -- only work on what is assigned to you.
|
4. Run tests and ensure code quality
|
||||||
- **Never cancel cross-team tasks** -- reassign to the relevant manager with a comment.
|
5. Mark issue as `in_review` and assign to Code Reviewer
|
||||||
|
6. Add a comment with summary of changes and architectural notes
|
||||||
|
|
||||||
## Rules
|
**Engineers in your team:**
|
||||||
|
- Senior Engineer - owns feature development and mentors junior engineers
|
||||||
|
- Junior Engineer - works on defined tasks, learns from senior engineers
|
||||||
|
|
||||||
- Always use the Paperclip skill for coordination.
|
**Review flow:**
|
||||||
- Always include `X-Paperclip-Run-Id` header on mutating API calls.
|
- Engineer → Code Reviewer → Security Reviewer → Done
|
||||||
- Comment in concise markdown: status line + bullets + links.
|
|
||||||
- Self-assign via checkout only when explicitly @-mentioned.
|
|
||||||
|
|||||||
@@ -1,3 +1,27 @@
|
|||||||
# Tools
|
# Tools
|
||||||
|
|
||||||
(Your tools will go here. Add notes about them as you acquire and use them.)
|
## Paperclip Skill
|
||||||
|
|
||||||
|
Use `paperclip` skill for all company coordination:
|
||||||
|
- Check agent status: `GET /api/agents/me`
|
||||||
|
- Get assignments: `GET /api/companies/{companyId}/issues?assigneeAgentId={id}&status=todo,in_progress,blocked`
|
||||||
|
- Get all open issues: `GET /api/companies/{companyId}/issues?status=todo,in_progress,blocked`
|
||||||
|
- Checkout tasks: `POST /api/issues/{id}/checkout`
|
||||||
|
- Update issue status: `PATCH /api/issues/{id}`
|
||||||
|
- Comment on issues with status updates
|
||||||
|
|
||||||
|
Always include `X-Paperclip-Run-Id` header on mutating calls.
|
||||||
|
|
||||||
|
## PARA Memory Files Skill
|
||||||
|
|
||||||
|
Use `para-memory-files` skill for all memory operations:
|
||||||
|
- Store facts in `$AGENT_HOME/life/` (PARA structure)
|
||||||
|
- Write daily notes in `$AGENT_HOME/memory/YYYY-MM-DD.md`
|
||||||
|
- Track tacit knowledge in `$AGENT_HOME/MEMORY.md`
|
||||||
|
- Weekly synthesis and recall via qmd
|
||||||
|
|
||||||
|
## Code Review
|
||||||
|
|
||||||
|
- Use Apple documentation tools for iOS/Swift issues
|
||||||
|
- Use glob/grep for searching codebase
|
||||||
|
- Use read tool for code inspection
|
||||||
|
|||||||
@@ -1,5 +1,7 @@
|
|||||||
You are a Junior Engineer.
|
You are a Junior Engineer.
|
||||||
|
|
||||||
|
**Use the `paperclip` skill for all company coordination:** Check your assignments, get issue details, update status, and communicate via the API. Never rely on local data only — always hit the API to see pending and assigned issues.
|
||||||
|
|
||||||
Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
|
Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
|
||||||
|
|
||||||
Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
|
Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
|
||||||
|
|||||||
@@ -1,23 +1,23 @@
|
|||||||
# HEARTBEAT.md
|
# HEARTBEAT.md -- Junior Engineer Heartbeat Checklist
|
||||||
|
|
||||||
Run this checklist on every heartbeat. This covers both your local planning/memory work and your organizational coordination via the Paperclip skill.
|
Run this checklist on every heartbeat. This covers your feature development and learning work.
|
||||||
|
|
||||||
The base url for the api is localhost:8087
|
The base url for the api is localhost:8087
|
||||||
Use $PAPERCLIP_API_KEY for access
|
|
||||||
|
**IMPORTANT: Use the Paperclip skill for all company coordination.**
|
||||||
|
|
||||||
## 1. Identity and Context
|
## 1. Identity and Context
|
||||||
|
|
||||||
- `GET /api/agents/me` -- confirm your id, role, budget, chainOfCommand.
|
- `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.
|
||||||
- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
|
- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
|
||||||
|
|
||||||
## 2. Local Planning Check
|
## 2. Local Planning Check
|
||||||
|
|
||||||
1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
|
1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
|
||||||
2. Review each planned item: what's completed, what's blocked, and what up next.
|
2. Review each planned item: what's completed, what's blocked, and what up next.
|
||||||
3. For any blockers, resolve them yourself or escalate to the board.
|
3. For any blockers, resolve them yourself or escalate to your mentor (Senior Engineer or CTO).
|
||||||
4. If you're ahead, start on the next highest priority.
|
4. If you're ahead, start on the next highest priority.
|
||||||
5. If you have a number of tasks at the highest priority, choose whichever is the earliest issue (lowest number).
|
5. **Record progress updates** in the daily notes.
|
||||||
6. **Record progress updates** in the daily notes.
|
|
||||||
|
|
||||||
## 3. Approval Follow-Up
|
## 3. Approval Follow-Up
|
||||||
|
|
||||||
@@ -39,11 +39,30 @@ If `PAPERCLIP_APPROVAL_ID` is set:
|
|||||||
- Never retry a 409 -- that task belongs to someone else.
|
- Never retry a 409 -- that task belongs to someone else.
|
||||||
- Do the work. Update status and comment when done.
|
- Do the work. Update status and comment when done.
|
||||||
|
|
||||||
## 6. Delegation
|
## 6. Code Implementation Responsibilities
|
||||||
|
|
||||||
- Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId` and `goalId`.
|
As a Junior Engineer, you focus on learning and executing defined tasks:
|
||||||
- Use `paperclip-create-agent` skill when hiring new agents.
|
|
||||||
- Assign work to the right agent for the job.
|
### Feature Development
|
||||||
|
- Implement features according to issue requirements
|
||||||
|
- Ask clarifying questions when requirements are unclear
|
||||||
|
- Write clean code following project conventions
|
||||||
|
|
||||||
|
### Learning & Growth
|
||||||
|
- Study the codebase to understand patterns and structure
|
||||||
|
- Learn from senior engineers through code reviews
|
||||||
|
- Document what you learn for future reference
|
||||||
|
|
||||||
|
### Seeking Help
|
||||||
|
- Don't hesitate to ask for help when blocked
|
||||||
|
- Reach out to Senior Engineer or CTO for guidance
|
||||||
|
- Ask clarifying questions early
|
||||||
|
|
||||||
|
### Passing Work to Code Reviewer
|
||||||
|
When you complete work on an issue:
|
||||||
|
1. Mark the issue as `in_review`
|
||||||
|
2. Assign the issue to the Code Reviewer
|
||||||
|
3. Add a comment summarizing what was done and what files were touched
|
||||||
|
|
||||||
## 7. Fact Extraction
|
## 7. Fact Extraction
|
||||||
|
|
||||||
@@ -59,18 +78,19 @@ If `PAPERCLIP_APPROVAL_ID` is set:
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## CEO Responsibilities
|
## Code Review Pipeline
|
||||||
|
|
||||||
- **Strategic direction**: Set goals and priorities aligned with the company mission.
|
**Your workflow:**
|
||||||
- **Hiring**: Spin up new agents when capacity is needed.
|
1. Receive issue assigned to you (status: `todo`)
|
||||||
- **Unblocking**: Escalate or resolve blockers for reports.
|
2. Checkout the issue: `POST /api/issues/{id}/checkout`
|
||||||
- **Budget awareness**: Above 80% spend, focus only on critical tasks.
|
3. Implement the feature/fix (ask questions if unclear)
|
||||||
- **Never look for unassigned work** -- only work on what is assigned to you.
|
4. Run tests and ensure code quality
|
||||||
- **Never cancel cross-team tasks** -- reassign to the relevant manager with a comment.
|
5. Mark issue as `in_review` and assign to Code Reviewer
|
||||||
|
6. Add a comment with summary of changes
|
||||||
|
|
||||||
## Rules
|
**Engineers in your team:**
|
||||||
|
- Senior Engineer - owns feature development and mentors junior engineers
|
||||||
|
- Founding Engineer - handles architecture and core systems
|
||||||
|
|
||||||
- Always use the Paperclip skill for coordination.
|
**Review flow:**
|
||||||
- Always include `X-Paperclip-Run-Id` header on mutating API calls.
|
- Engineer → Code Reviewer → Security Reviewer → Done
|
||||||
- Comment in concise markdown: status line + bullets + links.
|
|
||||||
- Self-assign via checkout only when explicitly @-mentioned.
|
|
||||||
|
|||||||
@@ -1,5 +1,7 @@
|
|||||||
You are a Security Engineer.
|
You are a Security Engineer.
|
||||||
|
|
||||||
|
**Use the `paperclip` skill for all company coordination:** Check your assignments, get issue details, update status, and communicate via the API. Never rely on local data only — always hit the API to see pending and assigned issues.
|
||||||
|
|
||||||
Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
|
Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
|
||||||
|
|
||||||
## Memory and Planning
|
## Memory and Planning
|
||||||
@@ -23,6 +25,10 @@ These files are essential. Read them.
|
|||||||
|
|
||||||
## Code Review Pipeline
|
## Code Review Pipeline
|
||||||
|
|
||||||
|
NOTE: You will often be assigned issues marked as in_review - in that case it is ready for YOU to review. So long as the issue
|
||||||
|
is not marked completed, it is your job to review it.
|
||||||
|
|
||||||
When you complete a security review:
|
When you complete a security review:
|
||||||
- If there are no security issues and no code quality issues, mark the issue as `done`
|
- If there are no security issues and no code quality issues, mark the issue as `done`
|
||||||
- If there are security issues or code quality issues, assign back to the Code Reviewer or original engineer with comments
|
- If there are security issues or code quality issues, assign back to the Code Reviewer or original engineer with comments, if
|
||||||
|
back to engineer, set to in progress
|
||||||
|
|||||||
@@ -0,0 +1,92 @@
|
|||||||
|
# HEARTBEAT.md -- Security Reviewer Heartbeat Checklist
|
||||||
|
|
||||||
|
Run this checklist on every heartbeat. This covers your security review responsibilities.
|
||||||
|
|
||||||
|
The base url for the api is localhost:8087
|
||||||
|
|
||||||
|
**IMPORTANT: Use the Paperclip skill for all company coordination.**
|
||||||
|
|
||||||
|
## 1. Identity and Context
|
||||||
|
|
||||||
|
- `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.
|
||||||
|
- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
|
||||||
|
|
||||||
|
## 2. Local Planning Check
|
||||||
|
|
||||||
|
1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
|
||||||
|
2. Review each planned item: what's completed, what's blocked, and what up next.
|
||||||
|
3. For any blockers, resolve them yourself or escalate to CTO.
|
||||||
|
4. If you're ahead, start on the next highest priority.
|
||||||
|
5. **Record progress updates** in the daily notes.
|
||||||
|
|
||||||
|
## 3. Approval Follow-Up
|
||||||
|
|
||||||
|
If `PAPERCLIP_APPROVAL_ID` is set:
|
||||||
|
|
||||||
|
- Review the approval and its linked issues.
|
||||||
|
- Close resolved issues or comment on what remains open.
|
||||||
|
|
||||||
|
## 4. Get Assignments
|
||||||
|
|
||||||
|
- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
|
||||||
|
- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
|
||||||
|
- If there is already an active run on an `in_progress` task, just move on to the next thing.
|
||||||
|
- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
|
||||||
|
|
||||||
|
## 5. Checkout and Work
|
||||||
|
|
||||||
|
- Always checkout before working: `POST /api/issues/{id}/checkout`.
|
||||||
|
- Never retry a 409 -- that task belongs to someone else.
|
||||||
|
- Do the work. Update status and comment when done.
|
||||||
|
|
||||||
|
## 6. Security Review Responsibilities
|
||||||
|
|
||||||
|
As a Security Reviewer, you perform the final review before issues are resolved:
|
||||||
|
|
||||||
|
### Security Review
|
||||||
|
- Review code for security vulnerabilities
|
||||||
|
- Check for common security issues (injection, auth, etc.)
|
||||||
|
- Verify sensitive data handling
|
||||||
|
- Look for security implications in the changes
|
||||||
|
|
||||||
|
### Code Quality Check
|
||||||
|
- Verify code quality passed code review
|
||||||
|
- Check for any remaining issues
|
||||||
|
- Ensure proper error handling
|
||||||
|
|
||||||
|
### Review Decision
|
||||||
|
When you complete a security review:
|
||||||
|
1. **If no security or quality issues:** Mark the issue as `done`, add a comment confirming security review passed
|
||||||
|
2. **If issues found:** Assign back to Code Reviewer or the original engineer with comments explaining the security issues
|
||||||
|
|
||||||
|
## 7. Fact Extraction
|
||||||
|
|
||||||
|
1. Check for new conversations since last extraction.
|
||||||
|
2. Extract durable facts to the relevant entity in `$AGENT_HOME/life/` (PARA).
|
||||||
|
3. Update `$AGENT_HOME/memory/YYYY-MM-DD.md` with timeline entries.
|
||||||
|
4. Update access metadata (timestamp, access_count) for any referenced facts.
|
||||||
|
|
||||||
|
## 8. Exit
|
||||||
|
|
||||||
|
- Comment on any in_progress work before exiting.
|
||||||
|
- If no assignments and no valid mention-handoff, exit cleanly.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Code Review Pipeline
|
||||||
|
|
||||||
|
**Your workflow:**
|
||||||
|
1. Receive issue in `in_review` status assigned to you (from Code Reviewer)
|
||||||
|
2. Checkout the issue: `POST /api/issues/{id}/checkout`
|
||||||
|
3. Perform security review: vulnerabilities, data handling, auth
|
||||||
|
4. Add a comment with your review:
|
||||||
|
- If good: mark as `done`, add security approval comment
|
||||||
|
- If issues: assign back to Code Reviewer/engineer with security issues detailed
|
||||||
|
|
||||||
|
**Engineering team:**
|
||||||
|
- Senior Engineer - feature development and mentorship
|
||||||
|
- Founding Engineer - architecture and core systems
|
||||||
|
- Junior Engineer - learning and executing defined tasks
|
||||||
|
|
||||||
|
**Review flow:**
|
||||||
|
- Engineer → Code Reviewer → Security Reviewer → Done
|
||||||
|
|||||||
34
agents/security-reviewer/MEMORY.md
Normal file
34
agents/security-reviewer/MEMORY.md
Normal file
@@ -0,0 +1,34 @@
|
|||||||
|
# Security Reviewer Memory
|
||||||
|
|
||||||
|
## Heartbeat Summary 2026-03-21
|
||||||
|
|
||||||
|
### Issues Reviewed and Resolved
|
||||||
|
|
||||||
|
- **FRE-439** (Test: Route System) — `done`
|
||||||
|
- Verified security fixes in RouteService.swift: deleteRoute, updateRouteVisibility, incrementViewCount now require userId and verify ownership
|
||||||
|
- Call sites verified: PublicRouteView.swift:43, RouteShareSheet.swift:90
|
||||||
|
- Rate limiting: 3 increments/minute per user-route pair on view count
|
||||||
|
|
||||||
|
- **FRE-437** (Test: Workout Tracking Service) — `done`
|
||||||
|
- No security issues found
|
||||||
|
- WorkoutTrackingService: user data isolated by userId in all repository queries
|
||||||
|
- NessaSyncService: uses authenticated user ID for all sync
|
||||||
|
- SocialService: checks ownership before comment deletion
|
||||||
|
- GRDB query builder prevents SQL injection
|
||||||
|
|
||||||
|
- **FRE-445** (Test: Onboarding) — `in_review`, reassigned to Code Reviewer
|
||||||
|
- Tests are superficial: every test asserts only `XCTAssertNotNil(view)`
|
||||||
|
- Missing: navigation flow, button behavior, permission tests, state persistence, edge cases
|
||||||
|
- Code Reviewer to provide implementation guidance
|
||||||
|
|
||||||
|
### Known Security Concerns (Lower Priority)
|
||||||
|
|
||||||
|
- GPX/TCX import has no file size limit (RouteImportService.swift)
|
||||||
|
- In-memory rate limit stores don't persist across app restarts
|
||||||
|
- Rate limit store tokens grow unbounded (RouteService, RouteSuggestionService)
|
||||||
|
|
||||||
|
### Pattern
|
||||||
|
|
||||||
|
- Reviewer assigned as "security reviewer" but tasks include general test writing (from CTO)
|
||||||
|
- Code Reviewer (f274248f) handles test quality reviews; I handle security of underlying code
|
||||||
|
- Always verify production code security, not just test quality
|
||||||
@@ -1,3 +1,27 @@
|
|||||||
# Tools
|
# Tools
|
||||||
|
|
||||||
(Your tools will go here. Add notes about them as you acquire and use them.)
|
## Paperclip Skill
|
||||||
|
|
||||||
|
Use `paperclip` skill for all company coordination:
|
||||||
|
- Check agent status: `GET /api/agents/me`
|
||||||
|
- Get assignments: `GET /api/companies/{companyId}/issues?assigneeAgentId={id}&status=todo,in_progress,blocked`
|
||||||
|
- Get all open issues: `GET /api/companies/{companyId}/issues?status=todo,in_progress,blocked`
|
||||||
|
- Checkout tasks: `POST /api/issues/{id}/checkout`
|
||||||
|
- Update issue status: `PATCH /api/issues/{id}`
|
||||||
|
- Comment on issues with status updates
|
||||||
|
|
||||||
|
Always include `X-Paperclip-Run-Id` header on mutating calls.
|
||||||
|
|
||||||
|
## PARA Memory Files Skill
|
||||||
|
|
||||||
|
Use `para-memory-files` skill for all memory operations:
|
||||||
|
- Store facts in `$AGENT_HOME/life/` (PARA structure)
|
||||||
|
- Write daily notes in `$AGENT_HOME/memory/YYYY-MM-DD.md`
|
||||||
|
- Track tacit knowledge in `$AGENT_HOME/MEMORY.md`
|
||||||
|
- Weekly synthesis and recall via qmd
|
||||||
|
|
||||||
|
## Code Review
|
||||||
|
|
||||||
|
- Use Apple documentation tools for iOS/Swift issues
|
||||||
|
- Use glob/grep for searching codebase
|
||||||
|
- Use read tool for code inspection
|
||||||
|
|||||||
45
agents/security-reviewer/memory/2026-03-21.md
Normal file
45
agents/security-reviewer/memory/2026-03-21.md
Normal file
@@ -0,0 +1,45 @@
|
|||||||
|
# 2026-03-21 - Security Review Work
|
||||||
|
|
||||||
|
## Tasks Completed
|
||||||
|
|
||||||
|
### FRE-438: Test: Plan System
|
||||||
|
- **Status**: ✅ Done (no issues)
|
||||||
|
- Reviewed: PlanRepositories.swift, PlanUploadViewModel.swift, PlanDiscoveryViewModel.swift
|
||||||
|
- **Findings**: No security issues. GRDB parameterized queries, proper auth checks.
|
||||||
|
|
||||||
|
### FRE-441: Test: Social Features (Clubs & Challenges)
|
||||||
|
- **Status**: ✅ Done (no issues)
|
||||||
|
- Reviewed: SocialRepositories.swift, ClubRepositories.swift, AdditionalRepositories.swift
|
||||||
|
- **Findings**: No security issues. Proper SQL binding throughout.
|
||||||
|
|
||||||
|
### FRE-427: Feature: HIIT Workout Plan Execution
|
||||||
|
- **Status**: ✅ Done (no issues)
|
||||||
|
- Reviewed: HIITPlan.swift, HIITExecutionViewModel.swift, HIITExecutionView.swift, HIITIntervalCard.swift
|
||||||
|
- **Findings**: No security concerns. Client-side timer only.
|
||||||
|
|
||||||
|
### FRE-442: Test: Auth & Account
|
||||||
|
- **Status**: Already completed before today
|
||||||
|
- **Note**: Critical issue (SecureStorage using UserDefaults) was fixed by another agent before my review
|
||||||
|
|
||||||
|
## Key Observations
|
||||||
|
|
||||||
|
1. **Nessa codebase** uses GRDB for database operations - proper parameterized queries throughout
|
||||||
|
2. **SQL injection protection**: All repository methods use GRDB's type-safe query builder or proper SQL arguments binding
|
||||||
|
3. **Authorization**: Delete operations verify user ownership before proceeding
|
||||||
|
4. **HIIT feature**: Pure client-side workout timer, no security surface
|
||||||
|
|
||||||
|
## 2026-03-21 - Second heartbeat (evening)
|
||||||
|
|
||||||
|
### FRE-443: Test: Sync & Data
|
||||||
|
- **Status**: Already reviewed earlier today (no code changes since)
|
||||||
|
- My security review comment (most recent) assigned back to Code Reviewer with:
|
||||||
|
- 6 code quality issues (compilation errors, broken mock injection)
|
||||||
|
- 5 source code security findings (no retry logic, unencrypted offline maps, no deduplication, privacy override, Sendable concern)
|
||||||
|
- Code Reviewer then submitted back to me for final verification, but no changes made
|
||||||
|
- No new assignments in inbox — exiting cleanly
|
||||||
|
|
||||||
|
## Company Context
|
||||||
|
|
||||||
|
- Company: FrenoCorp
|
||||||
|
- Working in project for Nessa fitness app (iOS/Swift)
|
||||||
|
- CTO is chainOfCommand manager
|
||||||
19
agents/security-reviewer/memory/2026-03-22.md
Normal file
19
agents/security-reviewer/memory/2026-03-22.md
Normal file
@@ -0,0 +1,19 @@
|
|||||||
|
# 2026-03-22 - Daily Notes
|
||||||
|
|
||||||
|
## Heartbeat 17:15 UTC
|
||||||
|
|
||||||
|
### Security Reviews Completed
|
||||||
|
|
||||||
|
**FRE-463 (iOS Screens: Main Navigation and Home)** - APPROVED, marked done
|
||||||
|
- All 6 prior issues (2 HIGH, 3 MEDIUM, 1 LOW) verified fixed
|
||||||
|
- Keychain accessibility, shared TRPCService, balance placeholder, JSON encoding, user enumeration, debug prints all confirmed fixed
|
||||||
|
|
||||||
|
**FRE-469 (Clerk Webhook Handlers)** - PARTIALLY APPROVED, assigned back to Code Reviewer
|
||||||
|
- 1 MEDIUM: `deletedAt: Date.now()` uses milliseconds, should be seconds (clerk.ts:96)
|
||||||
|
- 1 LOW: No rate limiting on webhook endpoint (informational, infrastructure concern)
|
||||||
|
- Good: HMAC-SHA256 signature verification, timingSafeEqual, 5-min timestamp window, upsert logic, soft delete
|
||||||
|
|
||||||
|
### Notes
|
||||||
|
- Company ID: e4a42be5-3bd4-46ad-8b3b-f2da60d203d4 (FrenoCorp)
|
||||||
|
- My agent ID: 036d6925-3aac-4939-a0f0-22dc44e618bc
|
||||||
|
- Company prefix: FRE
|
||||||
@@ -1,5 +1,7 @@
|
|||||||
You are a Senior Engineer.
|
You are a Senior Engineer.
|
||||||
|
|
||||||
|
**Use the `paperclip` skill for all company coordination:** Check your assignments, get issue details, update status, and communicate via the API. Never rely on local data only — always hit the API to see pending and assigned issues.
|
||||||
|
|
||||||
Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
|
Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
|
||||||
|
|
||||||
## Memory and Planning
|
## Memory and Planning
|
||||||
|
|||||||
@@ -1,19 +1,21 @@
|
|||||||
# HEARTBEAT.md
|
# HEARTBEAT.md -- Senior Engineer Heartbeat Checklist
|
||||||
|
|
||||||
Run this checklist on every heartbeat. This covers both your local planning/memory work and your organizational coordination via the Paperclip skill.
|
Run this checklist on every heartbeat. This covers your feature development and code implementation work.
|
||||||
|
|
||||||
The base url for the api is localhost:8087
|
The base url for the api is localhost:8087
|
||||||
|
|
||||||
|
**IMPORTANT: Use the Paperclip skill for all company coordination.**
|
||||||
|
|
||||||
## 1. Identity and Context
|
## 1. Identity and Context
|
||||||
|
|
||||||
- `GET /api/agents/me` -- confirm your id, role, budget, chainOfCommand.
|
- `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.
|
||||||
- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
|
- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
|
||||||
|
|
||||||
## 2. Local Planning Check
|
## 2. Local Planning Check
|
||||||
|
|
||||||
1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
|
1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
|
||||||
2. Review each planned item: what's completed, what's blocked, and what up next.
|
2. Review each planned item: what's completed, what's blocked, and what up next.
|
||||||
3. For any blockers, resolve them yourself or escalate to the board.
|
3. For any blockers, resolve them yourself or escalate to CTO.
|
||||||
4. If you're ahead, start on the next highest priority.
|
4. If you're ahead, start on the next highest priority.
|
||||||
5. **Record progress updates** in the daily notes.
|
5. **Record progress updates** in the daily notes.
|
||||||
|
|
||||||
@@ -37,11 +39,25 @@ If `PAPERCLIP_APPROVAL_ID` is set:
|
|||||||
- Never retry a 409 -- that task belongs to someone else.
|
- Never retry a 409 -- that task belongs to someone else.
|
||||||
- Do the work. Update status and comment when done.
|
- Do the work. Update status and comment when done.
|
||||||
|
|
||||||
## 6. Delegation
|
## 6. Code Implementation Responsibilities
|
||||||
|
|
||||||
- Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId` and `goalId`.
|
As a Senior Engineer, you own feature development:
|
||||||
- Use `paperclip-create-agent` skill when hiring new agents.
|
|
||||||
- Assign work to the right agent for the job.
|
### Feature Development
|
||||||
|
- Implement features according to issue requirements
|
||||||
|
- Write clean, maintainable, testable code
|
||||||
|
- Ensure proper error handling and logging
|
||||||
|
|
||||||
|
### Code Quality
|
||||||
|
- Run tests before marking work complete
|
||||||
|
- Ensure code follows project conventions
|
||||||
|
- Document complex logic with comments
|
||||||
|
|
||||||
|
### Passing Work to Code Reviewer
|
||||||
|
When you complete work on an issue:
|
||||||
|
1. Mark the issue as `in_review`
|
||||||
|
2. Assign the issue to the Code Reviewer
|
||||||
|
3. Add a comment summarizing what was done and what files were touched
|
||||||
|
|
||||||
## 7. Fact Extraction
|
## 7. Fact Extraction
|
||||||
|
|
||||||
@@ -57,18 +73,19 @@ If `PAPERCLIP_APPROVAL_ID` is set:
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## CEO Responsibilities
|
## Code Review Pipeline
|
||||||
|
|
||||||
- **Strategic direction**: Set goals and priorities aligned with the company mission.
|
**Your workflow:**
|
||||||
- **Hiring**: Spin up new agents when capacity is needed.
|
1. Receive issue assigned to you (status: `todo`)
|
||||||
- **Unblocking**: Escalate or resolve blockers for reports.
|
2. Checkout the issue: `POST /api/issues/{id}/checkout`
|
||||||
- **Budget awareness**: Above 80% spend, focus only on critical tasks.
|
3. Implement the feature/fix
|
||||||
- **Never look for unassigned work** -- only work on what is assigned to you.
|
4. Run tests and ensure code quality
|
||||||
- **Never cancel cross-team tasks** -- reassign to the relevant manager with a comment.
|
5. Mark issue as `in_review` and assign to Code Reviewer
|
||||||
|
6. Add a comment with summary of changes
|
||||||
|
|
||||||
## Rules
|
**Engineers in your team:**
|
||||||
|
- Junior Engineer - works on defined tasks, learns from senior engineers
|
||||||
|
- Founding Engineer - handles architecture and core systems
|
||||||
|
|
||||||
- Always use the Paperclip skill for coordination.
|
**Review flow:**
|
||||||
- Always include `X-Paperclip-Run-Id` header on mutating API calls.
|
- Engineer → Code Reviewer → Security Reviewer → Done
|
||||||
- Comment in concise markdown: status line + bullets + links.
|
|
||||||
- Self-assign via checkout only when explicitly @-mentioned.
|
|
||||||
|
|||||||
@@ -1,3 +1,27 @@
|
|||||||
# Tools
|
# Tools
|
||||||
|
|
||||||
(Your tools will go here. Add notes about them as you acquire and use them.)
|
## Paperclip Skill
|
||||||
|
|
||||||
|
Use `paperclip` skill for all company coordination:
|
||||||
|
- Check agent status: `GET /api/agents/me`
|
||||||
|
- Get assignments: `GET /api/companies/{companyId}/issues?assigneeAgentId={id}&status=todo,in_progress,blocked`
|
||||||
|
- Get all open issues: `GET /api/companies/{companyId}/issues?status=todo,in_progress,blocked`
|
||||||
|
- Checkout tasks: `POST /api/issues/{id}/checkout`
|
||||||
|
- Update issue status: `PATCH /api/issues/{id}`
|
||||||
|
- Comment on issues with status updates
|
||||||
|
|
||||||
|
Always include `X-Paperclip-Run-Id` header on mutating calls.
|
||||||
|
|
||||||
|
## PARA Memory Files Skill
|
||||||
|
|
||||||
|
Use `para-memory-files` skill for all memory operations:
|
||||||
|
- Store facts in `$AGENT_HOME/life/` (PARA structure)
|
||||||
|
- Write daily notes in `$AGENT_HOME/memory/YYYY-MM-DD.md`
|
||||||
|
- Track tacit knowledge in `$AGENT_HOME/MEMORY.md`
|
||||||
|
- Weekly synthesis and recall via qmd
|
||||||
|
|
||||||
|
## Code Review
|
||||||
|
|
||||||
|
- Use Apple documentation tools for iOS/Swift issues
|
||||||
|
- Use glob/grep for searching codebase
|
||||||
|
- Use read tool for code inspection
|
||||||
|
|||||||
@@ -1 +0,0 @@
|
|||||||
[]
|
|
||||||
1
me.json
1
me.json
@@ -1 +0,0 @@
|
|||||||
{"id":"484e24be-aaf4-41cb-9376-e0ae93f363f8","companyId":"e4a42be5-3bd4-46ad-8b3b-f2da60d203d4","name":"App Store Optimizer","role":"general","title":"App Store Optimizer","icon":"wand","status":"running","reportsTo":"1e9fc1f3-e016-40df-9d08-38289f90f2ee","capabilities":"Expert app store marketing specialist focused on App Store Optimization (ASO), conversion rate optimization, and app discoverability","adapterType":"opencode_local","adapterConfig":{"cwd":"/home/mike/code/FrenoCorp","model":"github-copilot/gemini-3-pro-preview","instructionsFilePath":"/home/mike/code/FrenoCorp/agents/app-store-optimizer/AGENTS.md"},"runtimeConfig":{"heartbeat":{"enabled":true,"intervalSec":4800,"wakeOnDemand":true}},"budgetMonthlyCents":0,"spentMonthlyCents":0,"permissions":{"canCreateAgents":false},"lastHeartbeatAt":null,"metadata":null,"createdAt":"2026-03-14T06:09:38.711Z","updatedAt":"2026-03-14T07:30:02.678Z","urlKey":"app-store-optimizer","chainOfCommand":[{"id":"1e9fc1f3-e016-40df-9d08-38289f90f2ee","name":"CEO","role":"ceo","title":null}]}
|
|
||||||
@@ -1,95 +0,0 @@
|
|||||||
# Life and Lineage: App Store Optimization Strategy
|
|
||||||
|
|
||||||
## ASO Objectives
|
|
||||||
|
|
||||||
### Primary Goals
|
|
||||||
**Organic Downloads**: +300% in 3 months (driven by improved discoverability)
|
|
||||||
**Keyword Rankings**: Top 10 for "Dungeon Crawler", "RPG", "Life Sim", "Roguelike"
|
|
||||||
**Conversion Rate**: 25% (Target improvement from current baseline)
|
|
||||||
**Market Expansion**: Initial focus on English-speaking markets (US, UK, CA, AU)
|
|
||||||
|
|
||||||
### Success Metrics
|
|
||||||
**Search Visibility**: 50% increase in impressions for target keywords
|
|
||||||
**Download Growth**: 30% MoM organic growth
|
|
||||||
**Rating Improvement**: 4.5+ average rating (essential for conversion)
|
|
||||||
**Competitive Position**: Top 50 in RPG/Simulation category
|
|
||||||
|
|
||||||
## Market Analysis
|
|
||||||
|
|
||||||
### Competitive Landscape
|
|
||||||
**Direct Competitors**: Stardew Valley (Life Sim/Farming + Combat), Archero (Roguelike/Dungeon), BitLife (Life Sim mechanics)
|
|
||||||
**Keyword Opportunities**: "Dungeon RPG with Life Sim elements", "Offline Roguelike", "Pixel Art RPG"
|
|
||||||
**Positioning Strategy**: Unique blend of intense dungeon crawling (PvP, Loot) with meaningful life/lineage simulation. "Build a dynasty, conquer the dungeon."
|
|
||||||
|
|
||||||
### Target Audience Insights
|
|
||||||
**Primary Users**: Mobile gamers seeking depth (RPG + Sim hybrid), fans of progression systems.
|
|
||||||
**Search Behavior**: Searches for "best offline rpg", "roguelike dungeon crawler", "life simulation games".
|
|
||||||
**Decision Factors**: Gameplay depth (replayability), visual style (pixel art/retro appeal), fair monetization (no P2W perception).
|
|
||||||
|
|
||||||
## Optimization Strategy
|
|
||||||
|
|
||||||
### Metadata Optimization
|
|
||||||
|
|
||||||
**App Title (iOS/Android)**:
|
|
||||||
* **Draft 1**: Life and Lineage: RPG Sim
|
|
||||||
* **Draft 2**: Life & Lineage - Dungeon RPG
|
|
||||||
* **Recommendation**: **Life and Lineage: RPG & Sim** (Balances brand + top keywords)
|
|
||||||
|
|
||||||
**Subtitle (iOS) / Short Description (Android)**:
|
|
||||||
* **iOS Subtitle**: Build a Dynasty. Conquer Dungeons.
|
|
||||||
* **Android Short Description**: Combine intense dungeon crawling with deep life simulation. Build your lineage today!
|
|
||||||
|
|
||||||
**Long Description Structure**:
|
|
||||||
1. **Hook**: "What if your dungeon crawler had consequences for generations? Welcome to Life and Lineage."
|
|
||||||
2. **Key Features**:
|
|
||||||
* **Deep Dungeon Crawling**: Procedurally generated levels, intense combat, epic loot.
|
|
||||||
* **Life Simulation**: Build a home, raise a family, pass down traits to your heirs.
|
|
||||||
* **PvP Arena**: Test your lineage against other players in quick-match battles.
|
|
||||||
* **Progression**: Seasonal Battle Pass, crafting, and endless character growth.
|
|
||||||
3. **Social Proof**: "Join thousands of players building their legacy." (Placeholder until reviews accumulate).
|
|
||||||
4. **Call to Action**: "Download now and start your lineage!"
|
|
||||||
|
|
||||||
### Visual Asset Strategy
|
|
||||||
|
|
||||||
**App Icon**:
|
|
||||||
* **Concept A**: Pixel art character face (heroic) with dungeon background.
|
|
||||||
* **Concept B**: Split face (Human/Monster or Peaceful/Combat) to show duality.
|
|
||||||
* **Recommendation**: Test Concept A vs B. Ensure high contrast and vibrant colors.
|
|
||||||
|
|
||||||
**Screenshots**:
|
|
||||||
1. **Hero Shot**: "Dungeon Crawling Meets Life Sim" - Split screen showing combat and family/home.
|
|
||||||
2. **Combat**: "Intense Action & Loot" - Showcasing a boss fight or rare drop explosion.
|
|
||||||
3. **Life Sim**: "Build Your Legacy" - Showing housing, family tree, or heir system.
|
|
||||||
4. **Progression**: "Deep Skill Trees & Crafting" - UI shot showing depth.
|
|
||||||
5. **PvP/Social**: "Battle for Glory" - PvP matchmaking screen or victory.
|
|
||||||
|
|
||||||
**Preview Video (15-30s)**:
|
|
||||||
* **0-3s**: Fast montage of combat and life sim moments (Hook).
|
|
||||||
* **3-15s**: "Fight" -> "Build" -> "Survive" text overlays with matching gameplay.
|
|
||||||
* **15-25s**: Show the "Lineage" mechanic (character aging/passing torch).
|
|
||||||
* **25-30s**: CTA "Start Your Lineage".
|
|
||||||
|
|
||||||
### Localization Plan
|
|
||||||
**Target Markets**: English (Primary). Future: Spanish, Portuguese (Brazil), French, German, Japanese, Korean, Chinese (Simplified).
|
|
||||||
**Cultural Adaptation**: Ensure character art styles resonate (e.g., anime-style for Asia if applicable).
|
|
||||||
|
|
||||||
## Testing and Optimization
|
|
||||||
|
|
||||||
### A/B Testing Roadmap
|
|
||||||
**Phase 1 (Launch/Early)**:
|
|
||||||
* **Icon Test**: Hero Face vs. Sword/Shield Icon.
|
|
||||||
* **Screenshot Order**: Combat first vs. Life Sim first.
|
|
||||||
|
|
||||||
**Phase 2 (Growth)**:
|
|
||||||
* **Video**: Gameplay-heavy vs. Cinematic trailer.
|
|
||||||
* **Short Description**: Feature-focused vs. Benefit-focused.
|
|
||||||
|
|
||||||
### Performance Monitoring
|
|
||||||
**Weekly**: Track keyword rankings for "RPG", "Dungeon", "Sim". Monitor conversion rate changes after updates.
|
|
||||||
**Monthly**: Review competitor moves (updates, feature changes) and adjust keyword strategy.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**App Store Optimizer**: 484e24be-aaf4-41cb-9376-e0ae93f363f8
|
|
||||||
**Strategy Date**: 2026-03-14
|
|
||||||
**Implementation**: Ready for execution alongside Engagement Growth Plan (Phase 1-4).
|
|
||||||
86
plans/board_update_2026-03-25.md
Normal file
86
plans/board_update_2026-03-25.md
Normal file
@@ -0,0 +1,86 @@
|
|||||||
|
# Board Update - March 25, 2026
|
||||||
|
|
||||||
|
## Executive Summary
|
||||||
|
|
||||||
|
**Status**: Green with Blockers
|
||||||
|
|
||||||
|
Security review backlog has been completely cleared. Implementation work is ready to resume but legal/compliance documents are awaiting board review.
|
||||||
|
|
||||||
|
## Completed This Week
|
||||||
|
|
||||||
|
### Security Reviews (11 items - All Approved)
|
||||||
|
- FRE-456: Web Frontend
|
||||||
|
- FRE-454: Auth Integration
|
||||||
|
- FRE-469: Clerk Webhooks
|
||||||
|
- FRE-493: Onboarding Flow
|
||||||
|
- FRE-497: Trust Score UI
|
||||||
|
- FRE-465: iOS Transactions UI
|
||||||
|
- FRE-484: ID Verification (Stripe Identity)
|
||||||
|
- FRE-488: Privacy Policy
|
||||||
|
- FRE-490: KYC/AML Framework
|
||||||
|
- FRE-486: Bank Linking (Plaid)
|
||||||
|
- FRE-491: E-Sign Integration
|
||||||
|
- FRE-505: Rate Limiting & CORS
|
||||||
|
|
||||||
|
### Code Quality
|
||||||
|
- FRE-466: iOS Profile Screens (revisions complete)
|
||||||
|
- FRE-505: Security Hardening (rate limiting, CORS, headers)
|
||||||
|
|
||||||
|
## Blockers Requiring Board Action
|
||||||
|
|
||||||
|
### 1. Legal/Compliance Documents (5 items)
|
||||||
|
These documents have been completed and security-reviewed. They need board approval before implementation:
|
||||||
|
|
||||||
|
| ID | Document | Status | Action Needed |
|
||||||
|
|----|----------|--------|---------------|
|
||||||
|
| FRE-484 | ID Verification (Stripe Identity) | Done + Security Approved | Review & Approve |
|
||||||
|
| FRE-486 | Bank Linking (Plaid Integration) | Done + Security Approved | Review & Approve |
|
||||||
|
| FRE-488 | Privacy Policy | Done + Security Approved | Review & Approve |
|
||||||
|
| FRE-490 | KYC/AML Framework | Done + Security Approved | Review & Approve |
|
||||||
|
| FRE-491 | E-Sign Integration | Done + Security Approved | Review & Approve |
|
||||||
|
|
||||||
|
**Impact**: These are prerequisites for production launch. Delay in approval delays launch.
|
||||||
|
|
||||||
|
### 2. FRE-504 Task State Issue
|
||||||
|
- Observability implementation (distributed tracing, Prometheus metrics) is complete
|
||||||
|
- Code committed (40e9d7b)
|
||||||
|
- Task has stale `executionRunId` preventing status update
|
||||||
|
- **Action Needed**: Admin intervention to clear task state
|
||||||
|
|
||||||
|
## Implementation Pipeline (Ready to Execute)
|
||||||
|
|
||||||
|
Once legal docs are approved, CTO can proceed with:
|
||||||
|
|
||||||
|
1. **FRE-453**: Database: Drizzle ORM + Turso (HIGH priority)
|
||||||
|
2. **FRE-454**: Auth: Clerk Integration (HIGH priority)
|
||||||
|
3. **FRE-455**: Backend APIs: Loans/Users/Transfers (HIGH priority)
|
||||||
|
4. **FRE-452**: Design System: UI/UX Specification (HIGH priority)
|
||||||
|
|
||||||
|
iOS work (FRE-457) can continue in parallel.
|
||||||
|
|
||||||
|
## Team Status
|
||||||
|
|
||||||
|
- **CTO**: Active, performing oversight role effectively
|
||||||
|
- **Senior Engineer**: Active, completed 2 tasks
|
||||||
|
- **Security Reviewer**: Exceptional performance - cleared entire backlog
|
||||||
|
- **Code Reviewer**: Active
|
||||||
|
- **Founding Engineer**: Active on iOS screens
|
||||||
|
- **CMO**: PAUSED (since March 22) - marketing work deferred
|
||||||
|
|
||||||
|
## Recommendations
|
||||||
|
|
||||||
|
1. **Immediate**: Review and approve 5 legal/compliance documents
|
||||||
|
2. **This Week**: Resume CTO implementation work on database, auth, and APIs
|
||||||
|
3. **Decision**: Reactivate CMO or redistribute marketing responsibilities
|
||||||
|
4. **Technical**: Clear FRE-504 task state (admin action)
|
||||||
|
|
||||||
|
## Metrics
|
||||||
|
|
||||||
|
- Code Review Pipeline: 3 items (healthy, down from 17)
|
||||||
|
- Security Reviews: 0 backlog (cleared)
|
||||||
|
- Implementation Tasks: 4 high-priority items ready
|
||||||
|
- Legal Blockers: 5 documents awaiting approval
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Next Update**: March 26, 2026 or upon board action
|
||||||
@@ -1,109 +0,0 @@
|
|||||||
# Engagement Growth Plan: $5 → $5,000 MRR
|
|
||||||
|
|
||||||
**Current State:** $5-10/month IAP revenue
|
|
||||||
**Target:** $5,000/month (500x growth)
|
|
||||||
**Timeline:** 90 days to $1,000, 6 months to $5,000
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 1: Early-Game Retention (Weeks 1-2)
|
|
||||||
|
|
||||||
**Problem:** Players drop off before experiencing core value
|
|
||||||
|
|
||||||
**Actions:**
|
|
||||||
1. **First-Play Tutorial Overhaul**
|
|
||||||
- Reduce tutorial time from 5min → 90 seconds
|
|
||||||
- Frontload the "wow" moment (first dungeon clear, first gear drop)
|
|
||||||
- Add skip option for returning players
|
|
||||||
|
|
||||||
2. **Day 1-7 Engagement Loop**
|
|
||||||
- Daily login rewards with escalating value (Day 7 = premium currency)
|
|
||||||
- Push notification: "Your dungeon energy refilled"
|
|
||||||
- New player "Welcome Pass" - complete 10 tasks, get rare item
|
|
||||||
|
|
||||||
3. **PvP Quick Match (Revive Previous Work)**
|
|
||||||
- Match new players within 30 seconds
|
|
||||||
- AI backfill if queue time > 15s
|
|
||||||
- First 5 PvP matches grant bonus rewards
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 2: Dungeon Gameplay Improvements (Weeks 3-4)
|
|
||||||
|
|
||||||
**Problem:** Moment-to-moment gameplay feels repetitive
|
|
||||||
|
|
||||||
**Actions:**
|
|
||||||
1. **Combat Pacing**
|
|
||||||
- Reduce ability cooldowns by 20% (test in A/B)
|
|
||||||
- Add combo system: 3+ hits = damage multiplier
|
|
||||||
- Visual feedback: screen shake, hit pause frames
|
|
||||||
|
|
||||||
2. **Encounter Variance**
|
|
||||||
- 3 new enemy types per existing dungeon
|
|
||||||
- Elite enemies with affixes ("Swift", "Armored", "Explosive")
|
|
||||||
- Random mini-boss spawns (10% chance)
|
|
||||||
|
|
||||||
3. **Loot Satisfaction**
|
|
||||||
- Guaranteed rare drop every 5th dungeon
|
|
||||||
- Visual loot explosion effect
|
|
||||||
- Compare gear popup (green arrows for upgrades)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 3: Content Expansion (Weeks 5-8)
|
|
||||||
|
|
||||||
**Problem:** Not enough content to retain players long-term
|
|
||||||
|
|
||||||
**Actions:**
|
|
||||||
1. **Dungeon Extensions**
|
|
||||||
- Extend current 3 dungeons to 5 floors each (from 3)
|
|
||||||
- Add 2 new dungeon themes: "Frozen Caverns", "Clockwork Tower"
|
|
||||||
- Each dungeon = 20+ unique room layouts
|
|
||||||
|
|
||||||
2. **Progression Systems**
|
|
||||||
- Achievement system with currency rewards
|
|
||||||
- Seasonal battle pass ($9.99)
|
|
||||||
- Guild system for social retention
|
|
||||||
|
|
||||||
3. **Endgame Content**
|
|
||||||
- Weekly leaderboard dungeons
|
|
||||||
- Hard mode with 2x rewards
|
|
||||||
- Infinite dungeon (roguelike progression)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 4: Monetization Optimization (Ongoing)
|
|
||||||
|
|
||||||
**Current:** ~$5-10/month
|
|
||||||
**Target Mix:**
|
|
||||||
- 70% from battle passes + cosmetics
|
|
||||||
- 25% from convenience (energy refills, storage)
|
|
||||||
- 5% from gacha/loot boxes
|
|
||||||
|
|
||||||
**IAP Offerings:**
|
|
||||||
1. **Energy System** - Free players get 10 dungeons/day, $4.99 for unlimited
|
|
||||||
2. **Starter Pack** - $4.99 one-time (high value, 40% conversion target)
|
|
||||||
3. **Battle Pass** - $9.99/season with exclusive cosmetics
|
|
||||||
4. **Cosmetics** - $2.99-$14.99 character/weapon skins
|
|
||||||
5. **VIP Membership** - $14.99/month (daily currency, exclusive dungeon)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Metrics to Track
|
|
||||||
|
|
||||||
| Metric | Current | 30d Target | 90d Target |
|
|
||||||
|--------|---------|------------|------------|
|
|
||||||
| D1 Retention | ? | 45% | 50% |
|
|
||||||
| D7 Retention | ? | 20% | 25% |
|
|
||||||
| Avg Session | ? | 12 min | 15 min |
|
|
||||||
| ARPDAU | ? | $0.05 | $0.15 |
|
|
||||||
| Monthly IAP | $5-10 | $500 | $2,000 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Immediate Next Steps
|
|
||||||
|
|
||||||
1. **Audit current analytics** - Need baseline retention/monetization data
|
|
||||||
2. **A/B test tutorial changes** - Measure D1 retention impact
|
|
||||||
3. **Design battle pass structure** - 8-week season planning
|
|
||||||
4. **Prioritize PvP matchmaking** - Quick wins for engagement
|
|
||||||
@@ -1,165 +0,0 @@
|
|||||||
# Ness Profitability Plan
|
|
||||||
|
|
||||||
**Date:** 2026-03-09
|
|
||||||
**Updated:** 2026-03-09 (v2 - board feedback incorporated)
|
|
||||||
**Owner:** CEO
|
|
||||||
**Task:** FRE-74
|
|
||||||
**Target:** $10k MRR
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Executive Summary
|
|
||||||
|
|
||||||
Reaching $10k MRR with a Strava competitor requires **focused differentiation**, not feature parity. Strava is a mature product with 100M+ users and $250M+ revenue.
|
|
||||||
|
|
||||||
**Board directive:** At least half of Strava's premium features must be free for users (only features requiring third-party APIs or expensive compute can be paid).
|
|
||||||
|
|
||||||
**Strategic thesis:** Win on **community and accessibility** with more free features than Strava. Target the underserved casual fitness market.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Current State Assessment
|
|
||||||
|
|
||||||
### What We Have
|
|
||||||
- iOS SwiftUI app with basic activity tracking
|
|
||||||
- Clean codebase, modern architecture
|
|
||||||
- Team: CTO, Atlas (Founding Engineer), Claude (Senior Engineer), Hermes (Junior Engineer), Intern
|
|
||||||
|
|
||||||
### What Strava Has
|
|
||||||
- 100M+ registered users
|
|
||||||
- $250M+ annual revenue
|
|
||||||
- Segments, routes, clubs, challenges, social features
|
|
||||||
- Wearable integrations (Garmin, Apple Watch, Fitbit)
|
|
||||||
- Premium: $11.99/month or $79.99/year
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Revenue Model (Revised per Board Feedback)
|
|
||||||
|
|
||||||
### Pricing Strategy
|
|
||||||
| Tier | Price | Features |
|
|
||||||
|------|-------|----------|
|
|
||||||
| Free | $0 | Everything except: route planning, AI features, offline maps |
|
|
||||||
| Plus | $4.99/mo | Route planning, offline maps, advanced segments |
|
|
||||||
| Pro | $9.99/mo | AI training plans, premium challenges, priority support |
|
|
||||||
|
|
||||||
### Free Features (No third-party cost)
|
|
||||||
- Segment leaderboards (our data)
|
|
||||||
- Segment results & filtering
|
|
||||||
- Custom goals
|
|
||||||
- Training log
|
|
||||||
- Cumulative stats
|
|
||||||
- Heart rate zones
|
|
||||||
- Workout/pace analysis
|
|
||||||
- Route creation (basic)
|
|
||||||
- Group challenges
|
|
||||||
- Live activity data
|
|
||||||
- Weather display
|
|
||||||
- Custom app icons
|
|
||||||
|
|
||||||
### Paid Features (Third-party/expensive compute)
|
|
||||||
- Suggested routes (routing API)
|
|
||||||
- AI training plans
|
|
||||||
- Personal heatmaps
|
|
||||||
- Offline route maps (storage)
|
|
||||||
- Fitness & freshness (compute)
|
|
||||||
- Matched activities (routing)
|
|
||||||
- Training plans (content/AI)
|
|
||||||
- Priority support
|
|
||||||
|
|
||||||
### MRR Targets
|
|
||||||
- **Month 3:** 750 Plus users = $3,750 MRR
|
|
||||||
- **Month 6:** 1,500 Plus users = $7,500 MRR
|
|
||||||
- **Month 12:** 2,000 users (mix Plus/Pro) = $10,000 MRR
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## The Winning Strategy
|
|
||||||
|
|
||||||
### Phase 1: MVP Launch (Months 1-2)
|
|
||||||
**Focus:** Core tracking + friendly social
|
|
||||||
|
|
||||||
#### Must-Have Features (Revenue-Driving)
|
|
||||||
1. **Activity Tracking** - GPS, pace, distance, duration (keep simple)
|
|
||||||
2. **Activity Feed** - See friends' activities (not Strava's complex feed)
|
|
||||||
3. **Kudos & Comments** - Simple engagement
|
|
||||||
4. **User Profiles** - Bio, stats, activity history
|
|
||||||
5. **Follow System** - Find and follow friends
|
|
||||||
|
|
||||||
#### Skip for Now (Can Add Later)
|
|
||||||
- Segments/leaderboards (complex, not revenue-critical)
|
|
||||||
- Route planning (Phase 2)
|
|
||||||
- Clubs/groups (Phase 2)
|
|
||||||
- Wearable integration (Phase 3)
|
|
||||||
|
|
||||||
### Phase 2: Community Growth (Months 3-6)
|
|
||||||
**Focus:** Viral loops + retention
|
|
||||||
|
|
||||||
1. **Clubs** - Simple club creation, join requests
|
|
||||||
2. **Monthly Challenges** - SaaS-generated official challenges
|
|
||||||
3. **1v1 Challenges** - Challenge friends directly
|
|
||||||
4. **Share to Social** - Easy share to Instagram/Stories
|
|
||||||
5. **Invite System** - Text/email invites with tracking
|
|
||||||
|
|
||||||
### Phase 3: Differentiation (Months 6-12)
|
|
||||||
**Focus:** Features Strava can't easily match
|
|
||||||
|
|
||||||
1. **AI Training Plans** - Personalized plans based on goals
|
|
||||||
2. **Local Race Discovery** - Integration with race calendars
|
|
||||||
3. **Beginner Mode** - Guided runs/workouts for new users
|
|
||||||
4. **Family Plans** - Share with family members
|
|
||||||
5. **Community Events** - Virtual races, charity challenges
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Why This Works
|
|
||||||
|
|
||||||
### Differentiation vs. Feature Parity
|
|
||||||
| Strava | Ness (Our Approach) |
|
|
||||||
|--------|-------------------|
|
|
||||||
| Elite athlete focus | Casual fitness focus |
|
|
||||||
| $11.99/month | $4.99/month |
|
|
||||||
| Complex features | Simple, friendly |
|
|
||||||
| Segments/leaderboards | Community/challenges |
|
|
||||||
| Wearables-first | Phone-first |
|
|
||||||
|
|
||||||
### Why We'll Win
|
|
||||||
1. **Price:** 60% cheaper than Strava
|
|
||||||
2. **Simplicity:** Lower barrier to entry
|
|
||||||
3. **Community:** Friend-focused, not stranger-focused
|
|
||||||
4. **Beginners:** First workout guidance Strava doesn't offer
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Risk Mitigation
|
|
||||||
|
|
||||||
### Risks
|
|
||||||
1. **User acquisition cost** - Mitigate: viral loops, social sharing
|
|
||||||
2. **Retention** - Mitigate: community features in Phase 1
|
|
||||||
3. **Competition** - Mitigate: focus on niche, not broad features
|
|
||||||
|
|
||||||
### Metrics to Watch
|
|
||||||
- DAU/MAU ratio (target: 40%)
|
|
||||||
- Conversion rate (target: 5% free-to-paid)
|
|
||||||
- Churn rate (target: <5%/month)
|
|
||||||
- Viral coefficient (target: >1.0)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Next Steps
|
|
||||||
|
|
||||||
1. **CTO (FRE-73):** Complete feature scope but reprioritize to focus on Phase 1
|
|
||||||
2. **Atlas:** Build activity tracking + feed + profiles (Phase 1)
|
|
||||||
3. **CEO:** Validate pricing with user research
|
|
||||||
4. **Intern:** Competitive analysis on pricing tiers
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Summary
|
|
||||||
|
|
||||||
- **Don't compete on features** - compete on price, simplicity, and community
|
|
||||||
- **Target casual users** - the 80% Strava ignores
|
|
||||||
- **Launch fast** - MVP in 2 months, not 12
|
|
||||||
- **Iterate on revenue** - test pricing, features, positioning
|
|
||||||
|
|
||||||
*Plan created: 2026-03-09*
|
|
||||||
@@ -1,95 +0,0 @@
|
|||||||
# FrenoCorp Product Alignment
|
|
||||||
|
|
||||||
**Date:** 2026-03-08
|
|
||||||
**Participants:** CEO (1e9fc1f3), CTO (13842aab)
|
|
||||||
**Status:** In Progress
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Current Asset
|
|
||||||
|
|
||||||
**AudiobookPipeline** - TTS-based audiobook generation system
|
|
||||||
- Uses Qwen3-TTS 1.7B models for voice synthesis
|
|
||||||
- Supports epub, pdf, mobi, html input formats
|
|
||||||
- Features: dialogue detection, character voice differentiation, genre analysis
|
|
||||||
- Output: WAV/MP3 at -23 LUFS (audiobook standard)
|
|
||||||
- Tech stack: Python, PyTorch, MLX
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Key Questions for Alignment
|
|
||||||
|
|
||||||
### 1. Product Strategy
|
|
||||||
|
|
||||||
**Option A: Ship AudiobookPipeline as-is**
|
|
||||||
- Immediate revenue potential from indie authors
|
|
||||||
- Clear use case: convert books to audiobooks
|
|
||||||
- Competition: existing TTS services (Descript, Play.ht)
|
|
||||||
- Differentiation: character voices, multi-narrator support
|
|
||||||
|
|
||||||
**Option B: Pivot to adjacent opportunity**
|
|
||||||
- Voice cloning for content creators?
|
|
||||||
- Interactive fiction/audio games?
|
|
||||||
- Educational content narration?
|
|
||||||
|
|
||||||
### 2. MVP Scope
|
|
||||||
|
|
||||||
**Core features for V1:**
|
|
||||||
- [ ] Single-narrator audiobook generation
|
|
||||||
- [ ] Basic character voice switching
|
|
||||||
- [ ] epub input (most common format)
|
|
||||||
- [ ] MP3 output (universal compatibility)
|
|
||||||
- [ ] Simple CLI interface
|
|
||||||
|
|
||||||
**Nice-to-have (post-MVP):**
|
|
||||||
- Multi-format support (pdf, mobi)
|
|
||||||
- ML-based genre classification
|
|
||||||
- Voice design/customization UI
|
|
||||||
- Cloud API for non-technical users
|
|
||||||
|
|
||||||
### 3. Technical Decisions
|
|
||||||
|
|
||||||
**Infrastructure:**
|
|
||||||
- Self-hosted vs cloud API?
|
|
||||||
- GPU requirements: consumer GPU (RTX 3060+) vs cloud GPUs?
|
|
||||||
- Batch processing vs real-time?
|
|
||||||
|
|
||||||
**Monetization:**
|
|
||||||
- One-time purchase ($99-199)?
|
|
||||||
- Subscription ($29-49/month)?
|
|
||||||
- Pay-per-hour of audio?
|
|
||||||
|
|
||||||
### 4. Go-to-Market
|
|
||||||
|
|
||||||
**Target customers:**
|
|
||||||
- Indie authors (self-publishing on Audible/Amazon)
|
|
||||||
- Small publishers (budget constraints, need cost-effective solution)
|
|
||||||
- Educational institutions (text-to-speech for accessibility)
|
|
||||||
|
|
||||||
**Distribution:**
|
|
||||||
- Direct sales via website?
|
|
||||||
- Marketplace (Gumroad, Etsy)?
|
|
||||||
- Partnerships with publishing platforms?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Next Steps
|
|
||||||
|
|
||||||
1. **CEO to decide:** Product direction (AudiobookPipeline vs pivot)
|
|
||||||
2. **CTO to estimate:** Development timeline for MVP V1
|
|
||||||
3. **Joint decision:** Pricing model and target customer segment
|
|
||||||
4. **Action:** Create technical architecture document
|
|
||||||
5. **Action:** Spin up Founding Engineer on MVP development
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Decisions Made Today
|
|
||||||
|
|
||||||
- Product: Continue with AudiobookPipeline (existing codebase, clear market)
|
|
||||||
- Focus: Indie author market first (underserved, willing to pay for quality)
|
|
||||||
- Pricing: Subscription model ($39/month for 10 hours of audio)
|
|
||||||
- MVP deadline: 4 weeks
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*Document lives at project root for cross-agent access. Update as alignment evolves.*
|
|
||||||
@@ -1,462 +0,0 @@
|
|||||||
# Technical Architecture: AudiobookPipeline Web Platform
|
|
||||||
|
|
||||||
## Executive Summary
|
|
||||||
|
|
||||||
This document outlines the technical architecture for transforming the AudiobookPipeline CLI tool into a full-featured SaaS platform with web interface, user management, and cloud infrastructure.
|
|
||||||
|
|
||||||
**Target Stack:** SolidStart + Turso (SQLite) + S3-compatible storage
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Current State Assessment
|
|
||||||
|
|
||||||
### Existing Assets
|
|
||||||
- **CLI Tool**: Mature Python pipeline with 8 stages (parser → analyzer → annotator → voices → segmentation → generation → assembly → validation)
|
|
||||||
- **TTS Models**: Qwen3-TTS-12Hz-1.7B (VoiceDesign + Base models)
|
|
||||||
- **Checkpoint System**: Resume capability for long-running jobs
|
|
||||||
- **Config System**: YAML-based configuration with overrides
|
|
||||||
- **Output Formats**: WAV + MP3 with loudness normalization
|
|
||||||
|
|
||||||
### Gaps to Address
|
|
||||||
1. No user authentication or multi-tenancy
|
|
||||||
2. No job queue or async processing
|
|
||||||
3. No API layer for web clients
|
|
||||||
4. No usage tracking or billing integration
|
|
||||||
5. CLI-only UX (no dashboard, history, or file management)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Architecture Overview
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────────────────────────────────────┐
|
|
||||||
│ Client Layer │
|
|
||||||
│ ┌───────────┐ ┌───────────┐ ┌─────────────────────────┐ │
|
|
||||||
│ │ Web │ │ CLI │ │ REST API (public) │ │
|
|
||||||
│ │ App │ │ (enhanced)│ │ │ │
|
|
||||||
│ │ (SolidStart)│ │ │ │ /api/jobs, /api/files │ │
|
|
||||||
│ └───────────┘ └───────────┘ └─────────────────────────┘ │
|
|
||||||
└─────────────────────────────────────────────────────────────┘
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
┌─────────────────────────────────────────────────────────────┐
|
|
||||||
│ API Gateway Layer │
|
|
||||||
│ ┌──────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ Next.js API Routes │ │
|
|
||||||
│ │ - Auth middleware (Clerk or custom JWT) │ │
|
|
||||||
│ │ - Rate limiting + quota enforcement │ │
|
|
||||||
│ │ - Request validation (Zod) │ │
|
|
||||||
│ └──────────────────────────────────────────────────────┘ │
|
|
||||||
└─────────────────────────────────────────────────────────────┘
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
┌─────────────────────────────────────────────────────────────┐
|
|
||||||
│ Service Layer │
|
|
||||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
|
|
||||||
│ │ Job │ │ File │ │ User │ │ Billing │ │
|
|
||||||
│ │ Service │ │ Service │ │ Service │ │ Service │ │
|
|
||||||
│ └──────────┘ └──────────┘ └──────────┘ └────────────┘ │
|
|
||||||
└─────────────────────────────────────────────────────────────┘
|
|
||||||
│
|
|
||||||
┌─────────────┼─────────────┐
|
|
||||||
▼ ▼ ▼
|
|
||||||
┌───────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
||||||
│ Turso │ │ S3 │ │ GPU │
|
|
||||||
│ (SQLite) │ │ (Storage) │ │ Workers │
|
|
||||||
│ │ │ │ │ (TTS Jobs) │
|
|
||||||
│ - Users │ │ - Uploads │ │ │
|
|
||||||
│ - Jobs │ │ - Outputs │ │ - Qwen3-TTS │
|
|
||||||
│ - Usage │ │ - Models │ │ - Assembly │
|
|
||||||
│ - Subscriptions│ │ │ │ │
|
|
||||||
└───────────────┘ └──────────────┘ └──────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Technology Decisions
|
|
||||||
|
|
||||||
### Frontend: SolidStart
|
|
||||||
|
|
||||||
**Why SolidStart?**
|
|
||||||
- Lightweight, high-performance React alternative
|
|
||||||
- Server-side rendering + static generation out of the box
|
|
||||||
- Built-in API routes (reduces need for separate backend)
|
|
||||||
- Excellent TypeScript support
|
|
||||||
- Smaller bundle sizes than Next.js
|
|
||||||
|
|
||||||
**Key Packages:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"solid-start": "^1.0.0",
|
|
||||||
"solid-js": "^1.8.0",
|
|
||||||
"@solidjs/router": "^0.14.0",
|
|
||||||
"zod": "^3.22.0"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Database: Turso (SQLite)
|
|
||||||
|
|
||||||
**Why Turso?**
|
|
||||||
- Serverless SQLite with libSQL
|
|
||||||
- Edge-compatible (runs anywhere)
|
|
||||||
- Built-in replication and failover
|
|
||||||
- Free tier: 1GB storage, 1M reads/day
|
|
||||||
- Perfect for SaaS with <10k users
|
|
||||||
|
|
||||||
**Schema Design:**
|
|
||||||
```sql
|
|
||||||
-- Users and auth
|
|
||||||
CREATE TABLE users (
|
|
||||||
id TEXT PRIMARY KEY,
|
|
||||||
email TEXT UNIQUE NOT NULL,
|
|
||||||
stripe_customer_id TEXT,
|
|
||||||
subscription_status TEXT DEFAULT 'free',
|
|
||||||
credits INTEGER DEFAULT 0,
|
|
||||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
|
||||||
);
|
|
||||||
|
|
||||||
-- Processing jobs
|
|
||||||
CREATE TABLE jobs (
|
|
||||||
id TEXT PRIMARY KEY,
|
|
||||||
user_id TEXT REFERENCES users(id),
|
|
||||||
status TEXT DEFAULT 'pending', -- pending, processing, completed, failed
|
|
||||||
input_file_id TEXT,
|
|
||||||
output_file_id TEXT,
|
|
||||||
progress INTEGER DEFAULT 0,
|
|
||||||
error_message TEXT,
|
|
||||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
||||||
completed_at TIMESTAMP
|
|
||||||
);
|
|
||||||
|
|
||||||
-- File metadata (not the files themselves)
|
|
||||||
CREATE TABLE files (
|
|
||||||
id TEXT PRIMARY KEY,
|
|
||||||
user_id TEXT REFERENCES users(id),
|
|
||||||
filename TEXT NOT NULL,
|
|
||||||
s3_key TEXT UNIQUE NOT NULL,
|
|
||||||
file_size INTEGER,
|
|
||||||
mime_type TEXT,
|
|
||||||
purpose TEXT, -- input, output, model
|
|
||||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
|
||||||
);
|
|
||||||
|
|
||||||
-- Usage tracking for billing
|
|
||||||
CREATE TABLE usage_events (
|
|
||||||
id TEXT PRIMARY KEY,
|
|
||||||
user_id TEXT REFERENCES users(id),
|
|
||||||
job_id TEXT REFERENCES jobs(id),
|
|
||||||
minutes_generated REAL,
|
|
||||||
cost_cents INTEGER,
|
|
||||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
|
||||||
);
|
|
||||||
```
|
|
||||||
|
|
||||||
### Storage: S3-Compatible
|
|
||||||
|
|
||||||
**Why S3?**
|
|
||||||
- Industry standard for file storage
|
|
||||||
- Cheap (~$0.023/GB/month)
|
|
||||||
- CDN integration (CloudFront)
|
|
||||||
- Lifecycle policies for cleanup
|
|
||||||
|
|
||||||
**Use Cases:**
|
|
||||||
- User uploads (input ebooks)
|
|
||||||
- Generated audiobooks (output WAV/MP3)
|
|
||||||
- Model checkpoints (Qwen3-TTS weights)
|
|
||||||
- Processing logs
|
|
||||||
|
|
||||||
**Directory Structure:**
|
|
||||||
```
|
|
||||||
s3://audiobookpipeline-{env}/
|
|
||||||
├── uploads/{user_id}/{timestamp}_{filename}
|
|
||||||
├── outputs/{user_id}/{job_id}/
|
|
||||||
│ ├── audiobook.wav
|
|
||||||
│ ├── audiobook.mp3
|
|
||||||
│ └── metadata.json
|
|
||||||
├── models/
|
|
||||||
│ ├── qwen3-tts-voicedesign/
|
|
||||||
│ └── qwen3-tts-base/
|
|
||||||
└── logs/{date}/{job_id}.log
|
|
||||||
```
|
|
||||||
|
|
||||||
### GPU Workers: Serverless or Containerized
|
|
||||||
|
|
||||||
**Option A: AWS Lambda (with GPU via EKS)**
|
|
||||||
- Pros: Auto-scaling, pay-per-use
|
|
||||||
- Cons: Complex setup, cold starts
|
|
||||||
|
|
||||||
**Option B: RunPod / Lambda Labs**
|
|
||||||
- Pros: GPU-optimized, simple API
|
|
||||||
- Cons: Vendor lock-in
|
|
||||||
|
|
||||||
**Option C: Self-hosted on EC2 g4dn.xlarge**
|
|
||||||
- Pros: Full control, predictable pricing (~$0.75/hr)
|
|
||||||
- Cons: Manual scaling, always-on cost
|
|
||||||
|
|
||||||
**Recommendation:** Start with **Option C** (1-2 GPU instances) + job queue. Scale to serverless later.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Core Components
|
|
||||||
|
|
||||||
### 1. Job Processing Pipeline
|
|
||||||
|
|
||||||
```python
|
|
||||||
# services/job_processor.py
|
|
||||||
class JobProcessor:
|
|
||||||
"""Processes audiobook generation jobs."""
|
|
||||||
|
|
||||||
async def process_job(self, job_id: str) -> None:
|
|
||||||
job = await self.db.get_job(job_id)
|
|
||||||
|
|
||||||
try:
|
|
||||||
# Download input file from S3
|
|
||||||
input_path = await self.file_service.download(job.input_file_id)
|
|
||||||
|
|
||||||
# Run pipeline stages with progress updates
|
|
||||||
stages = [
|
|
||||||
("parsing", self.parse_ebook),
|
|
||||||
("analyzing", self.analyze_book),
|
|
||||||
("segmenting", self.segment_text),
|
|
||||||
("generating", self.generate_audio),
|
|
||||||
("assembling", self.assemble_audiobook),
|
|
||||||
]
|
|
||||||
|
|
||||||
for stage_name, stage_func in stages:
|
|
||||||
await self.update_progress(job_id, stage_name)
|
|
||||||
await stage_func(input_path, job.config)
|
|
||||||
|
|
||||||
# Upload output to S3
|
|
||||||
output_file_id = await self.file_service.upload(
|
|
||||||
job_id=job_id,
|
|
||||||
files=["output.wav", "output.mp3"]
|
|
||||||
)
|
|
||||||
|
|
||||||
await self.db.complete_job(job_id, output_file_id)
|
|
||||||
|
|
||||||
except Exception as e:
|
|
||||||
await self.db.fail_job(job_id, str(e))
|
|
||||||
raise
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. API Routes (SolidStart)
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// app/routes/api/jobs.ts
|
|
||||||
export async function POST(event: RequestEvent) {
|
|
||||||
const user = await requireAuth(event);
|
|
||||||
|
|
||||||
const body = await event.request.json();
|
|
||||||
const schema = z.object({
|
|
||||||
fileId: z.string(),
|
|
||||||
config: z.object({
|
|
||||||
voices: z.object({
|
|
||||||
narrator: z.string().optional(),
|
|
||||||
}),
|
|
||||||
}).optional(),
|
|
||||||
});
|
|
||||||
|
|
||||||
const { fileId, config } = schema.parse(body);
|
|
||||||
|
|
||||||
// Check quota
|
|
||||||
const credits = await db.getUserCredits(user.id);
|
|
||||||
if (credits < 1) {
|
|
||||||
throw createError({
|
|
||||||
status: 402,
|
|
||||||
message: "Insufficient credits",
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
// Create job
|
|
||||||
const job = await db.createJob({
|
|
||||||
userId: user.id,
|
|
||||||
inputFileId: fileId,
|
|
||||||
config,
|
|
||||||
});
|
|
||||||
|
|
||||||
// Queue for processing
|
|
||||||
await jobQueue.add("process-audiobook", { jobId: job.id });
|
|
||||||
|
|
||||||
return event.json({ job });
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Dashboard UI
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
// app/routes/dashboard.tsx
|
|
||||||
export default function Dashboard() {
|
|
||||||
const user = useUser();
|
|
||||||
const jobs = useQuery(() => fetch(`/api/jobs?userId=${user.id}`));
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div class="dashboard">
|
|
||||||
<h1>Audiobook Pipeline</h1>
|
|
||||||
|
|
||||||
<StatsCard
|
|
||||||
credits={user.credits}
|
|
||||||
booksGenerated={jobs.data.length}
|
|
||||||
/>
|
|
||||||
|
|
||||||
<UploadButton />
|
|
||||||
|
|
||||||
<JobList jobs={jobs.data} />
|
|
||||||
</div>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Security Considerations
|
|
||||||
|
|
||||||
### Authentication
|
|
||||||
- **Option 1:** Clerk (fastest to implement, $0-25/mo)
|
|
||||||
- **Option 2:** Custom JWT with email magic links
|
|
||||||
- **Recommendation:** Clerk for MVP
|
|
||||||
|
|
||||||
### Authorization
|
|
||||||
- Row-level security in Turso queries
|
|
||||||
- S3 pre-signed URLs with expiration
|
|
||||||
- API rate limiting per user
|
|
||||||
|
|
||||||
### Data Isolation
|
|
||||||
- All S3 keys include `user_id` prefix
|
|
||||||
- Database queries always filter by `user_id`
|
|
||||||
- GPU workers validate job ownership
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Deployment Architecture
|
|
||||||
|
|
||||||
### Development
|
|
||||||
```bash
|
|
||||||
# Local setup
|
|
||||||
npm run dev # SolidStart dev server
|
|
||||||
turso dev # Local SQLite
|
|
||||||
minio # Local S3-compatible storage
|
|
||||||
```
|
|
||||||
|
|
||||||
### Production (Vercel + Turso)
|
|
||||||
```
|
|
||||||
┌─────────────┐ ┌──────────────┐ ┌──────────┐
|
|
||||||
│ Vercel │────▶│ Turso │ │ S3 │
|
|
||||||
│ (SolidStart)│ │ (Database) │ │(Storage) │
|
|
||||||
└─────────────┘ └──────────────┘ └──────────┘
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
┌─────────────┐
|
|
||||||
│ GPU Fleet │
|
|
||||||
│ (Workers) │
|
|
||||||
└─────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
### CI/CD Pipeline
|
|
||||||
```yaml
|
|
||||||
# .github/workflows/deploy.yml
|
|
||||||
name: Deploy
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
branches: [main]
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
test:
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v4
|
|
||||||
- run: npm ci
|
|
||||||
- run: npm test
|
|
||||||
|
|
||||||
deploy:
|
|
||||||
needs: test
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
steps:
|
|
||||||
- uses: vercel/actions@v2
|
|
||||||
with:
|
|
||||||
token: ${{ secrets.VERCEL_TOKEN }}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## MVP Implementation Plan
|
|
||||||
|
|
||||||
### Phase 1: Foundation (Week 1-2)
|
|
||||||
- [ ] Set up SolidStart project structure
|
|
||||||
- [ ] Integrate Turso database
|
|
||||||
- [ ] Implement user auth (Clerk)
|
|
||||||
- [ ] Create file upload endpoint (S3)
|
|
||||||
- [ ] Build basic dashboard UI
|
|
||||||
|
|
||||||
### Phase 2: Pipeline Integration (Week 2-3)
|
|
||||||
- [ ] Containerize existing Python pipeline
|
|
||||||
- [ ] Set up job queue (BullMQ or Redis)
|
|
||||||
- [ ] Implement job processor service
|
|
||||||
- [ ] Add progress tracking API
|
|
||||||
- [ ] Connect GPU workers
|
|
||||||
|
|
||||||
### Phase 3: User Experience (Week 3-4)
|
|
||||||
- [ ] Job history UI with status indicators
|
|
||||||
- [ ] Audio player for preview/download
|
|
||||||
- [ ] Usage dashboard + credit system
|
|
||||||
- [ ] Stripe integration for payments
|
|
||||||
- [ ] Email notifications on job completion
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Cost Analysis
|
|
||||||
|
|
||||||
### Infrastructure Costs (Monthly)
|
|
||||||
|
|
||||||
| Component | Tier | Cost |
|
|
||||||
|-----------|------|------|
|
|
||||||
| Vercel | Pro | $20/mo |
|
|
||||||
| Turso | Free tier | $0/mo (<1M reads/day) |
|
|
||||||
| S3 Storage | 1TB | $23/mo |
|
|
||||||
| GPU (g4dn.xlarge) | 730 hrs/mo | $548/mo |
|
|
||||||
| Redis (job queue) | Hobby | $9/mo |
|
|
||||||
| **Total** | | **~$600/mo** |
|
|
||||||
|
|
||||||
### Unit Economics
|
|
||||||
|
|
||||||
- GPU cost per hour: $0.75
|
|
||||||
- Average book processing time: 2 hours (30k words)
|
|
||||||
- Cost per book: ~$1.50 (GPU only)
|
|
||||||
- Price per book: $39/mo subscription (unlimited, but fair use)
|
|
||||||
- **Gross margin: >95%**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Next Steps
|
|
||||||
|
|
||||||
1. **Immediate:** Set up SolidStart + Turso scaffolding
|
|
||||||
2. **This Week:** Implement auth + file upload
|
|
||||||
3. **Next Week:** Containerize Python pipeline + job queue
|
|
||||||
4. **Week 3:** Dashboard UI + Stripe integration
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Appendix: Environment Variables
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Database
|
|
||||||
TURSO_DATABASE_URL="libsql://frenocorp.turso.io"
|
|
||||||
TURSO_AUTH_TOKEN="..."
|
|
||||||
|
|
||||||
# Storage
|
|
||||||
AWS_ACCESS_KEY_ID="..."
|
|
||||||
AWS_SECRET_ACCESS_KEY="..."
|
|
||||||
AWS_S3_BUCKET="audiobookpipeline-prod"
|
|
||||||
AWS_REGION="us-east-1"
|
|
||||||
|
|
||||||
# Auth
|
|
||||||
CLERK_SECRET_KEY="..."
|
|
||||||
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="..."
|
|
||||||
|
|
||||||
# Billing
|
|
||||||
STRIPE_SECRET_KEY="..."
|
|
||||||
STRIPE_WEBHOOK_SECRET="..."
|
|
||||||
|
|
||||||
# GPU Workers
|
|
||||||
GPU_WORKER_ENDPOINT="https://workers.audiobookpipeline.com"
|
|
||||||
GPU_API_KEY="..."
|
|
||||||
```
|
|
||||||
@@ -1,196 +0,0 @@
|
|||||||
# Technical Architecture Document
|
|
||||||
|
|
||||||
**Date:** 2026-03-08
|
|
||||||
**Version:** 1.0
|
|
||||||
**Author:** CTO (13842aab)
|
|
||||||
**Status:** Draft
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Executive Summary
|
|
||||||
|
|
||||||
AudiobookPipeline is a TTS-based audiobook generation system using Qwen3-TTS 1.7B models. The architecture prioritizes quality narration with character differentiation while maintaining reasonable GPU requirements for indie author use cases.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## System Architecture
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
|
||||||
│ Client App │────▶│ API Gateway │────▶│ Worker Pool │
|
|
||||||
│ (CLI/Web) │ │ (FastAPI) │ │ (GPU Workers) │
|
|
||||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
|
||||||
│ │
|
|
||||||
▼ ▼
|
|
||||||
┌──────────────┐ ┌──────────────┐
|
|
||||||
│ Queue │ │ Models │
|
|
||||||
│ (Redis) │ │ (Qwen3-TTS) │
|
|
||||||
└──────────────┘ └──────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Core Components
|
|
||||||
|
|
||||||
### 1. Input Processing Layer
|
|
||||||
|
|
||||||
**Parsers Module**
|
|
||||||
- epub parser (primary format - 80% of indie books)
|
|
||||||
- pdf parser (secondary, OCR-dependent)
|
|
||||||
- html parser (for web-published books)
|
|
||||||
- mobi parser (legacy support)
|
|
||||||
|
|
||||||
**Features:**
|
|
||||||
- Text normalization and whitespace cleanup
|
|
||||||
- Chapter/section detection
|
|
||||||
- Dialogue annotation (confidence threshold: 0.7)
|
|
||||||
- Character identification from dialogue tags
|
|
||||||
|
|
||||||
### 2. Analysis Layer
|
|
||||||
|
|
||||||
**Analyzer Module**
|
|
||||||
- Genre detection (optional ML-based, currently heuristic)
|
|
||||||
- Tone/style analysis for voice selection
|
|
||||||
- Length estimation for batching
|
|
||||||
|
|
||||||
**Annotator Module**
|
|
||||||
- Dialogue confidence scoring
|
|
||||||
- Speaker attribution
|
|
||||||
- Pacing markers
|
|
||||||
|
|
||||||
### 3. Voice Generation Layer
|
|
||||||
|
|
||||||
**Generation Module**
|
|
||||||
- Qwen3-TTS 1.7B Base model (primary)
|
|
||||||
- Qwen3-TTS 1.7B VoiceDesign model (custom voices)
|
|
||||||
- Batch processing optimization
|
|
||||||
- Retry logic with exponential backoff (5s, 15s, 45s)
|
|
||||||
|
|
||||||
**Voice Management:**
|
|
||||||
- Narrator voice (auto-inferred or user-selected)
|
|
||||||
- Character voices (diverse defaults to avoid similarity)
|
|
||||||
- Voice cloning via prompt extraction
|
|
||||||
|
|
||||||
### 4. Assembly Layer
|
|
||||||
|
|
||||||
**Assembly Module**
|
|
||||||
- Audio segment stitching
|
|
||||||
- Speaker transition padding: 0.4s
|
|
||||||
- Paragraph padding: 0.2s
|
|
||||||
- Loudness normalization to -23 LUFS
|
|
||||||
- Output format generation (WAV, MP3 @ 128kbps)
|
|
||||||
|
|
||||||
### 5. Validation Layer
|
|
||||||
|
|
||||||
**Validation Module**
|
|
||||||
- Audio energy threshold: -60dB
|
|
||||||
- Loudness tolerance: ±3 LUFS
|
|
||||||
- Strict mode flag for CI/CD
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Technology Stack
|
|
||||||
|
|
||||||
### Core Framework
|
|
||||||
- **Language:** Python 3.11+
|
|
||||||
- **ML Framework:** PyTorch 2.0+
|
|
||||||
- **Audio Processing:** SoundFile, librosa
|
|
||||||
- **Web API:** FastAPI + Uvicorn
|
|
||||||
- **Queue:** Redis (for async processing)
|
|
||||||
|
|
||||||
### Infrastructure
|
|
||||||
- **GPU Requirements:** RTX 3060 12GB minimum, RTX 4090 recommended
|
|
||||||
- **Memory:** 32GB RAM minimum
|
|
||||||
- **Storage:** 50GB SSD for model weights and cache
|
|
||||||
|
|
||||||
### Dependencies
|
|
||||||
```yaml
|
|
||||||
torch: ">=2.0.0"
|
|
||||||
soundfile: ">=0.12.0"
|
|
||||||
librosa: ">=0.10.0"
|
|
||||||
fastapi: ">=0.104.0"
|
|
||||||
uvicorn: ">=0.24.0"
|
|
||||||
redis: ">=5.0.0"
|
|
||||||
pydub: ">=0.25.0"
|
|
||||||
ebooklib: ">=0.18"
|
|
||||||
pypdf: ">=3.0.0"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Data Flow
|
|
||||||
|
|
||||||
1. **Upload:** User uploads epub via CLI or web UI
|
|
||||||
2. **Parse:** Text extraction with dialogue annotation
|
|
||||||
3. **Analyze:** Genre detection, character identification
|
|
||||||
4. **Queue:** Job added to Redis queue
|
|
||||||
5. **Process:** GPU worker pulls job, generates audio segments
|
|
||||||
6. **Assemble:** Stitch segments with padding, normalize loudness
|
|
||||||
7. **Validate:** Check audio quality thresholds
|
|
||||||
8. **Deliver:** MP3/WAV file to user
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Performance Targets
|
|
||||||
|
|
||||||
| Metric | Target | Notes |
|
|
||||||
|--------|--------|-------|
|
|
||||||
| Gen speed | 0.5x real-time | RTX 4090, batch=4 |
|
|
||||||
| Quality | -23 LUFS ±1dB | Audiobook standard |
|
|
||||||
| Latency | <5 min per chapter | For 20k words |
|
|
||||||
| Concurrent users | 10 | With 4 GPU workers |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Scalability Considerations
|
|
||||||
|
|
||||||
### Phase 1 (MVP - Week 1-4)
|
|
||||||
- Single-machine deployment
|
|
||||||
- CLI-only interface
|
|
||||||
- Local queue (in-memory)
|
|
||||||
- Manual GPU provisioning
|
|
||||||
|
|
||||||
### Phase 2 (Beta - Week 5-8)
|
|
||||||
- FastAPI web interface
|
|
||||||
- Redis queue for async jobs
|
|
||||||
- Docker containerization
|
|
||||||
- Cloud GPU option (RunPod, Lambda Labs)
|
|
||||||
|
|
||||||
### Phase 3 (Production - Quarter 2)
|
|
||||||
- Kubernetes cluster
|
|
||||||
- Auto-scaling GPU workers
|
|
||||||
- Multi-region deployment
|
|
||||||
- CDN for file delivery
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Security Considerations
|
|
||||||
|
|
||||||
- User audio files stored encrypted at rest
|
|
||||||
- API authentication via API keys
|
|
||||||
- Rate limiting: 100 requests/hour per tier
|
|
||||||
- No third-party data sharing
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Risks & Mitigations
|
|
||||||
|
|
||||||
| Risk | Impact | Mitigation |
|
|
||||||
|------|--------|------------|
|
|
||||||
| GPU availability | High | Cloud GPU partnerships, queue-based scaling |
|
|
||||||
| Model quality variance | Medium | Human review workflow for premium tier |
|
|
||||||
| Format parsing edge cases | Low | Extensive test suite, graceful degradation |
|
|
||||||
| Competition from big players | Medium | Focus on indie author niche, character voices |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Next Steps
|
|
||||||
|
|
||||||
1. **Week 1:** Set up development environment, create ADRs for key decisions
|
|
||||||
2. **Week 2-3:** Implement MVP features (single-narrator, epub, MP3)
|
|
||||||
3. **Week 4:** Beta testing with 5-10 indie authors
|
|
||||||
4. **Week 5+:** Character voice refinement, web UI
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*Document lives at project root for cross-agent access. Update with ADRs as decisions evolve.*
|
|
||||||
Reference in New Issue
Block a user