Skip to content

README.md

Latest commit

 

History

History
411 lines (334 loc) · 21.9 KB

README.md

File metadata and controls

411 lines (334 loc) · 21.9 KB
Raw

Yoak — Cofounder Agent Harness

Yoak is the harness for your cofounder agent ⸻ the one you talk to when you're searching for a repeatable business. Reinforced context including essays from Paul Graham, textbooks from Steve Blank, and curated interviews with Steve Jobs provide valuable founder level discussion about the most important parts of your startup. Yoak asks the hard questions, tracks what you've actually validated, and won't let you confuse hope for evidence.

Yoak is not a frontier model. It's a cofounder harness around the model you choose (Ollama locally by default, or Claude/GPT/DeepSeek via API). The harness is what makes it Yoak:

  • Persistent memory — Lean Canvas, hypotheses, learning journal
  • Structured workflows — idea evaluation, customer discovery, validation, pivot decisions
  • Encoded frameworks — PG instincts + Blank Customer Development + Jobs taste
  • Interfaces — terminal chat, web dashboard, Obsidian export

You interact with Yoak, your cofounder agent. Under the hood, an orchestrator assembles context from your startup's state, calls your configured LLM, and writes what you learn back to SQLite.

Yoak vs a chat wrapper

Generic LLM chat Yoak
Forgets your canvas between sessions Remembers canvas, hypotheses, and journal
Gives encouraging advice Pushback-focused cofounder persona
No structured phases Customer Development workflows with steps
You manage the process Agent routes to workflows and skills automatically

Why Yoak?

Every startup begins with untested assumptions. Most founders execute instead of learning — building features nobody wants, scaling before finding fit, ignoring the hard questions.

Yoak encodes three complementary worldviews as the cofounder agent's operating system:

Layer Thinker Role in Yoak
Instincts Paul Graham How to evaluate ideas, recognize what matters, use growth as a compass
Methodology Steve Blank Customer Development — the structured search for a repeatable business model
Taste Steve Jobs Product quality, simplicity, starting from the customer experience

The result is an AI cofounder that asks the questions you're avoiding, challenges your assumptions with frameworks, and keeps you honest about what's validated versus what's hoped for.

Quick Start

Copy and paste this into your terminal:

git clone https://github.com/Schellbach/yoak.git && cd yoak && make

That's it, one line. It clones the repo, installs everything, and drops you into a conversation with your cofounder agent. The web dashboard starts in the background. No API key needed. First run takes about a minute; every run after is instant.

Want to use a frontier model?

export ANTHROPIC_API_KEY="sk-ant-..."   # or OPENAI_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, ZHIPUAI_API_KEY
make init                               # picks up the key, lets you switch

Commands

make                   # start chatting (web UI starts in the background)
make chat              # go straight to chat (web UI starts in the background)
make serve             # start only the web dashboard (foreground)
make canvas            # print your Lean Canvas
make hypotheses        # list hypotheses
make journal           # show your learning journal
make export ARGS="--vault ~/Obsidian/MyVault"  # one-way Obsidian export
make init              # reconfigure model, project name, etc.
make help              # show all commands

The first time you run make or make chat, Yoak builds the dashboard with npm (Node.js required once) and starts it in the background at http://127.0.0.1:8420. Use make serve if you only want the web UI without terminal chat.

Prerequisites

  • Python 3.10+
  • Ollama (free local AI) is offered during first-run setup.
  • Web UI requires Node.js 18+

Architecture

Yoak is a cofounder agent harness: interfaces and orchestration on top, swappable LLM on the bottom, startup memory in the middle.

┌─────────────────────────────────────────────────────────────────┐
│                         INTERFACES                              │
│   Web Dashboard (React)              CLI (Typer)                │
└──────────┬───────────────────────────────┬──────────────────────┘
           │                               │
┌──────────▼───────────────────────────────▼──────────────────────┐
│                        API LAYER                                │
│   FastAPI (31 endpoints)         WebSocket (streaming chat)     │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                      YOAK AGENT HARNESS                         │
│                                                                 │
│   Agent Orchestrator ─── assembles system prompt from:          │
│     ├─ Philosophy Engine (PG + Blank + Jobs)                    │
│     ├─ Memory Context (canvas, hypotheses, journal)             │
│     ├─ Workflow Context (active step + prompt supplement)       │
│     └─ Skill Context (market analysis, user research, etc.)    │
│                                                                 │
│   Workflow Router ─── detects intent, dispatches to:            │
│     ├─ 6 Workflows (idea eval, discovery, validation, ...)     │
│     └─ 5 Skills (market, competition, growth, economics, ...)  │
└──────────┬──────────────────────────────┬───────────────────────┘
           │                              │
┌──────────▼──────────┐    ┌──────────────▼───────────────────────┐
│   MEMORY (SQLite)   │    │   MODEL LAYER (swappable)          │
│                     │    │                                    │
│ Lean Canvas         │    │  LiteLLM (Anthropic, OpenAI,       │
│   (9 blocks)        │    │    DeepSeek, Google, Zhipu, …)     │
│ Hypothesis Tracker  │    │  Ollama (llama, mistral,           │
│   + status history  │    │    codellama, gemma, phi, …)       │
│ Learning Journal    │    │                                    │
│   (incl. pivots)    │    │  Not part of Yoak — you choose     │
└─────────────────────┘    └────────────────────────────────────┘

Features

Encoded Philosophy (~21,000 chars of startup methodology)

Paul Graham — Instincts (source essays)

  • The "well, not field" test — prefer desperate need from a few over mild interest from many
  • Schlep blindness bypass — scary ideas are undervalued signals
  • Growth as compass — target 5-7% weekly, measure rate not absolute
  • Anti-patterns: sitcom startups, premature scaling, big launch fallacy, playing house
  • "Relentlessly resourceful" — the goal is fixed, the path is fluid

Steve Blank — Methodology (source writing)

  • Customer Development 4-phase state machine (Discovery → Validation → Creation → Building)
  • Lean Canvas as a living hypothesis board (9 blocks, each testable)
  • MVP type selection (concierge, wizard of oz, landing page, single-feature, pre-order)
  • Pivot decision framework with 10 pivot types and structured criteria
  • Product/Market Fit measurement (Sean Ellis test, retention curves, LTV/CAC)
  • Interview protocols: problem interviews, solution interviews, debrief synthesis
  • 2026 concepts: MVP → MPO (Minimum Productive Outcome), P/M Fit → Agent/Customer Outcome Fit

Steve Jobs — Taste

  • "Start with the customer experience, work backwards to technology"
  • Simplicity as highest sophistication — strip until only the essential remains
  • Focus means saying no to 100 good ideas
  • Craft: quality must be consistent throughout, even in hidden details
  • Empathy + Focus + Impute as the product evaluation triad

Workflows (Multi-Step Guided Processes)

Workflow Steps What It Does
Idea Evaluation 5 PG filters, Lean Canvas mapping, riskiest assumption, scoring
Customer Discovery 5 Hypothesis review, interview planning, debrief, solution testing, phase gate
Customer Validation 6 MVP development, earlyvangelist sales, sales roadmap, unit economics, P/M Fit, phase gate
Pivot Decision 5 Evidence review, signal analysis, diagnosis, pivot type selection, new hypothesis
PMF Assessment 3 Qualitative signals, quantitative metrics, diagnosis
Product Critique 4 Experience-first review, simplicity audit, focus/quality audit, verdict

Workflows are state machines — each step injects specific prompts that guide the conversation. The agent automatically routes to the right workflow based on what you're discussing.

Skills (Single-Turn Expertise)

Skill What It Provides
Market Analysis TAM/SAM/SOM sizing, market type classification, timing analysis
User Research Interview script generation, problem/solution templates, insight synthesis
Competitive Intel Competitor mapping, moat analysis, the "do nothing" competitor
Growth Strategy Growth engine selection (sticky/viral/paid), metric frameworks, PG growth principles
Unit Economics CAC/LTV modeling, burn rate, payback period, the "default alive" test

Memory (Persistent State)

All state is stored in a local SQLite database (~/.yoak/yoak.db):

  • Lean Canvas — Problem, Solution, Unique Value Proposition, Unfair Advantage, Customer Segments, Cost Structure, Revenue Streams, Channels, Key Metrics
  • Hypothesis Tracker — lifecycle management: untested → testing → validated/invalidated, with linked evidence entries and status history
  • Learning Journal — append-only log with types: learning, pivot, decision, milestone, interview, experiment
  • Phase Tracker — which Customer Development phase you're in (discovery, validation, creation, building)

Memory context is injected into every conversation turn, so the agent always knows your current canvas state, active hypotheses, and recent learnings.

Dashboard (Web UI)

Start with make, make chat, or yoak serve. The war room runs at http://127.0.0.1:8420 with six views:

  • Overview — Customer Development phase tracker, hypothesis stats (untested/testing/validated/invalidated), active workflow progress, recent activity
  • Chat — Streaming conversation with the cofounder agent, workflow phase indicator, suggested starter prompts
  • Canvas — Visual 9-block Lean Canvas with inline editing, version snapshots, compare mode, and per-block hypotheses
  • Hypotheses — Full list of testable beliefs with status filters, evidence, and links back to canvas blocks
  • Journal — Filterable timeline of learnings, pivots, decisions, experiments with inline creation
  • Settings — Model provider configuration (cloud + Ollama), temperature, project name

CLI

yoak chat      — Interactive terminal chat with the cofounder agent
yoak serve     — Start the API server + dashboard
yoak init      — First-time setup or reconfigure (project name, model)
yoak canvas    — Display the current Lean Canvas
yoak hypotheses — List hypotheses linked to the Lean Canvas
yoak journal   — Show recent learning journal entries
yoak export    — Export memory to an Obsidian vault (one-way)
yoak config    — Manage configuration (show, set)

In chat mode (CLI only), slash commands are intercepted before they reach the model:

Command Description
/canvas Print the current Lean Canvas
/workflow Show active workflow, or start one: /workflow idea_evaluation
/advance Manually advance the active workflow step
/phase Show current phase, or set it: /phase validation
/chatreset Clear conversation history and active workflow
/canvasreset Clear canvas blocks and hypotheses
/reset Clear chat, canvas, and learning journal (full fresh start)
/model Show the configured model
/quit Exit chat

The dashboard uses buttons and API calls instead of slash commands. In chat, you can also ask naturally (e.g. “show the canvas”) — that is handled by the agent, not the slash-command router.

Obsidian export (one-way)

Export Yoak's SQLite memory (Lean Canvas, hypotheses, evidence, journal, pivots) into an Obsidian vault as markdown plus a JSON Canvas file. Direction is DB → vault only. The vault output is generated and disposable; Yoak never reads it back.

yoak export --vault ~/Obsidian/MyVault
yoak export                              # uses saved vault path from config
yoak export --project mango-trees        # output under <vault>/yoak/mango-trees/
yoak export --force                      # regenerate without confirmation

Output layout:

<vault>/yoak/<project-slug>/
  Dashboard.md
  <project-slug>.canvas
  canvas/01 Problem.md … 09 Key Metrics.md
  hypotheses/H-<id>-<slug>.md
  journal/YYYY-MM-DD.md
  pivots/P-<id>-<slug>.md

Rules:

  • Files Yoak writes include yoak_managed: true in frontmatter.
  • Yoak skips any existing file that is not yoak-managed (prints a warning).
  • Re-export deletes stale yoak-managed hypothesis/pivot/journal files whose IDs or dates no longer exist in the DB.
  • Hypothesis status history is tracked in SQLite and exported under ## History.

Model Support

Yoak defaults to Ollama (free, local, private — no API key needed). To upgrade to a frontier model, just set an API key and run yoak init.

Provider Model String Setup
Ollama (default) ollama/llama3.1 brew install ollama && ollama pull llama3.1
Anthropic anthropic/claude-sonnet-4-20250514 export ANTHROPIC_API_KEY=...
OpenAI gpt-4o export OPENAI_API_KEY=...
DeepSeek deepseek/deepseek-chat export DEEPSEEK_API_KEY=...
Google gemini/gemini-2.5-pro export GEMINI_API_KEY=...
Zhipu (GLM) zhipuai/glm-4-flash export ZHIPUAI_API_KEY=...
Mistral mistral/mistral-large-latest export MISTRAL_API_KEY=...

Any model supported by LiteLLM works. Run yoak init to switch models at any time.

Project Structure

yoak/
├── pyproject.toml              # Package definition, dependencies
├── README.md
├── yoak/
│   ├── core/
│   │   ├── agent.py            # Main orchestrator — routes through philosophy + workflows
│   │   ├── router.py           # Intent detection → workflow/skill dispatch
│   │   └── config.py           # YAML-backed settings with env var support
│   ├── models/
│   │   ├── provider.py         # Unified LiteLLM + Ollama interface
│   │   └── streaming.py        # Streaming chunk accumulator
│   ├── philosophy/
│   │   ├── graham.py           # PG heuristics as callable prompt modules
│   │   ├── blank.py            # Customer Dev methodology + phase guidance
│   │   ├── jobs.py             # Product design principles + critique
│   │   └── synthesis.py        # Combined context builder + intent detection
│   ├── memory/
│   │   ├── store.py            # SQLite schema + connection management
│   │   ├── canvas.py           # Lean Canvas CRUD + summary renderer
│   │   ├── hypotheses.py       # Hypothesis lifecycle, evidence, status history
│   │   └── journal.py          # Learning journal + phase management
│   ├── export/
│   │   ├── runner.py           # One-way Obsidian vault export orchestration
│   │   ├── writers.py          # Markdown note builders (canvas, hypotheses, journal, pivots)
│   │   └── canvas.py           # JSON Canvas file for Obsidian
│   ├── workflows/
│   │   ├── base.py             # Base workflow state machine
│   │   ├── idea_evaluation.py  # 5-step PG-inspired idea scoring
│   │   ├── customer_discovery.py   # Blank Phase 1
│   │   ├── customer_validation.py  # Blank Phase 2
│   │   ├── pivot_decision.py   # Structured pivot-or-persevere
│   │   ├── pmf_assessment.py   # Product/Market Fit measurement
│   │   └── product_critique.py # Jobs-inspired quality review
│   ├── skills/
│   │   ├── market_analysis.py  # TAM/SAM/SOM, market types
│   │   ├── user_research.py    # Interview scripts, synthesis
│   │   ├── competitive_intel.py # Competitor mapping, moats
│   │   ├── growth_strategy.py  # Growth engine, metrics
│   │   └── unit_economics.py   # CAC/LTV, burn rate
│   ├── prompts/
│   │   ├── system/             # 4 system prompts (cofounder identity, PG, Blank, Jobs)
│   │   ├── workflows/          # 6 workflow prompts (idea eval, discovery, validation, ...)
│   │   └── skills/             # 5 skill prompts (market, interviews, competition, ...)
│   ├── api/
│   │   ├── app.py              # FastAPI app with 31 routes
│   │   └── routes/             # Endpoint modules (chat, canvas, hypotheses, journal, ...)
│   └── cli/
│       └── main.py             # Typer CLI with Rich formatting
└── dashboard/
    ├── package.json
    └── src/
        ├── App.tsx             # Router + icon sidebar
        ├── api/client.ts       # Full API client + WebSocket
        └── pages/              # Overview, Chat, Canvas, Hypotheses, Journal, Settings

How It Works

When you send a message to the cofounder agent, Yoak:

  1. Detects intent — maps your message to a workflow (multi-step) or skill (single-turn)
  2. Assembles context — builds a system prompt from:
    • The master cofounder identity prompt
    • Relevant PG/Blank/Jobs principles (based on your topic)
    • Your current Lean Canvas state
    • Recent learning journal entries
    • Active workflow step (if any) with its specific guidance prompt
    • Or the relevant skill prompt (if routed to a skill)
  3. Calls your model — sends the assembled messages to the LLM you configured (not baked into Yoak)
  4. Streams the response — via WebSocket (dashboard) or terminal (CLI)
  5. Persists what matters — canvas updates, hypotheses, and journal entries land in SQLite

The cofounder persona is consistent across all interactions: direct, honest, occasionally uncomfortable — like a great cofounder who asks the hard questions.

API Reference

The API runs on http://127.0.0.1:8420 with interactive docs at /docs.

Method Endpoint Description
POST /api/chat Send a message, get a response
WS /api/ws/chat Streaming chat via WebSocket
POST /api/chat/reset Clear conversation history and active workflow
GET /api/chat/history Get conversation messages
GET /api/canvas Get all 9 Lean Canvas blocks with hypotheses
PUT /api/canvas/{block_id} Update a canvas block
POST /api/canvas/reset Clear canvas blocks and hypotheses
GET /api/hypotheses List hypotheses (filter by block, status)
POST /api/hypotheses Create a hypothesis
PATCH /api/hypotheses/{id} Update status/confidence
POST /api/hypotheses/{id}/evidence Add evidence to a hypothesis
DELETE /api/hypotheses/{id} Delete a hypothesis
GET /api/journal List journal entries (filter by type)
POST /api/journal Create a journal entry
GET /api/phase Get current Customer Development phase
PUT /api/phase Set phase (discovery/validation/creation/building)
GET /api/workflows List available workflows
POST /api/workflows/start Start a workflow by name
POST /api/workflows/advance Advance to next workflow step
POST /api/workflows/cancel Cancel active workflow
GET /api/config Get current configuration
PUT /api/config Update a configuration value

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run the linter
ruff check yoak/

# Run the dashboard in dev mode (hot reload)
cd dashboard && npm run dev

Configuration

Yoak stores configuration in ~/.yoak/config.yaml (override with YOAK_DIR env var). project_name is your startup's name — not "yoak" (Yoak is always the agent; your startup is what you're building).

model:
  provider: ollama
  model: ollama/llama3.1
  temperature: 0.7
  max_tokens: 4096
ollama:
  enabled: true
  base_url: http://localhost:11434
  model: llama3.1
server:
  host: 127.0.0.1
  port: 8420
export:
  vault_path: null          # saved after first successful yoak export
  project_slug: null        # defaults to slugified project_name
project_name: My Startup

License

MIT