How We Work

This document defines the product development and governance structure for Surfc. It covers roles, responsibilities, the workflow loop, and how decisions are made. It is the reference document for any future collaborator joining the project.

Roles and responsibilities

Surfc operates with three functional roles. Currently all human responsibilities are held by one person (Deji), with Claude Code acting as the engineering agent.

Product Owner — Deji

Decides what gets built and why.

Owns the product vision and roadmap
Writes and prioritises Issues in Linear
Defines acceptance criteria for each feature
Accepts or rejects completed work
Makes all monetisation and user-facing decisions
Owns the CHANGELOG and release notes
Tags releases on GitHub

Engineer — Claude Code

Implements what the Product Owner specifies.

Reads the codebase and understands context before acting
Works exclusively on feature branches, never directly on main
Follows all conventions in CLAUDE.md
Runs npm run build before finishing any task
Writes clear PR summaries explaining what changed and why
Flags ambiguities or risks before implementing — does not make product decisions unilaterally
Raises blockers immediately rather than working around them silently

Reviewer / QA — Deji (+ future collaborator)

Ensures quality before anything reaches users.

Reviews all PRs before merge
Tests changes on real devices (desktop + Android S25 Ultra)
Checks that acceptance criteria in the Issue are met
Verifies the build deploys correctly to Netlify after merge

The workflow loop

Every piece of work — feature, fix, or chore — follows this loop:

1. ISSUE CREATED
   Product Owner writes a GitHub Issue using the appropriate template.
   Issue includes: what, why, acceptance criteria, priority label.
   Issue is added to the Linear board and assigned to a Milestone.

2. BRANCH CREATED
   Claude Code creates a feature branch from main:
   feat/short-description, fix/short-description, chore/short-description

3. IMPLEMENTATION
   Claude Code works on the branch, committing logical units of work.
   Conventional Commits format throughout.
   Build must pass before work is considered complete.

4. PULL REQUEST
   Claude Code pushes the branch and writes a PR summary:
   - What changed
   - Why
   - How to test it
   - Any open questions or known limitations
   Links to the originating Issue.

5. REVIEW
   Product Owner reviews the PR, tests on device.
   Either approves and merges, or requests changes with specific feedback.

6. DEPLOY
   Merge to main triggers automatic Netlify deployment.
   Product Owner verifies the deploy in production.

7. CLOSE
   Issue closed in Linear.
   CHANGELOG updated if user-visible change.
   Release tagged if this completes a Milestone.

Issue writing guide

A well-written Issue is the difference between Claude Code delivering exactly what you wanted and delivering something that needs three rounds of revision.

Required fields for every Issue

Title — type: short description e.g. feat: Readwise integration

What — one paragraph describing the feature or fix from the user’s perspective. Write it as: “As a user, I want to… so that…”

Why — one sentence on the business or user value.

Acceptance criteria — a checklist. Claude Code uses this to know when it’s done.

- [ ] User can connect their Readwise account via API token in Settings
- [ ] Highlights are imported with book title and author auto-populated
- [ ] Duplicate imports are skipped (merge by highlight ID)
- [ ] Works offline — queued and synced when reconnected

Out of scope — explicitly list what this Issue does NOT cover. This prevents scope creep and stops Claude Code from over-building.

Labels — feature, bug, chore, docs, refactor + priority: p0, p1, p2

Decision log

Significant product decisions are recorded here so they can be referenced later.

Date	Decision	Reasoning
2026-03	Centralised API key deferred to v1.3	Monetisation model must be defined first; BYOK retained for free tier
2026-03	Linear chosen over Trello for issue tracking	Native GitHub integration reduces manual overhead
2026-03	Supabase Edge Functions chosen for API proxy	Already in stack, integrates with Auth for request verification
2026-03	Soft deletes only	Hard deletes break sync when a device is offline during deletion
2026-03	Last-write-wins conflict resolution	Sufficient for single-user; CRDT not warranted at this stage

Branching and release rules

main is always deployable — Netlify watches it
All work on feature branches — merged via PR
Branch naming: feature/, fix/, chore/, docs/
Releases tagged with semver: v1.0.0, v1.1.0, v1.1.1
CHANGELOG updated before tagging a release
Tags pushed to GitHub: git push --tags

Onboarding a collaborator

When a human collaborator joins:

Give them read/write access to the GitHub repo
Add them to the Linear project
Walk them through this document and docs/architecture.md
Have them set up locally following the README
First PR should be a small, low-risk change to build familiarity with the workflow
They take on the Reviewer role initially before taking on implementation work