Skip to content

Build FounderOS as a local Markdown/YAML spine, not an app

Context

Considered building a full "Founder OS" — dashboard, CLI, automation suite — to manage multiple projects (StampReady, KindredPics, future). That would be weeks of work before any payoff and would duplicate things Claude Code + memory already do.

Decision

Start with Phase 1: a plain folder of Markdown + YAML under C:\Users\devin\FounderOS\. No code, no DB, no automation. Just:

  • projects/<slug>.yaml — single source of truth per project (state, stack, env, gotchas)
  • decisions/YYYY-MM-DD-*.md — dated ADRs for non-obvious choices
  • playbooks/*.md — reusable workflows
  • checklists/*.md — pre-flight lists

Add automation only when a workflow is repeated twice and proven painful.

Why this over the full build

  1. Token-efficient. A 60-line YAML feeds an agent more usable state than spelunking ~/.claude/projects memory.
  2. Reversible. If it turns out useless, it's a folder — rm -rf and done.
  3. Compounds. Project YAMLs become the answer to "what is this thing?" for any new agent (Claude, Codex, future).
  4. No premature abstraction. The "spine" is the deliverable. Tools attach later.

What this is NOT

  • Not a replacement for ~/.claude/projects/.../memory/ (auto-memory still owns conversational facts).
  • Not a dashboard. Not a CLI.
  • Not a project-management tool — that's still TodoWrite + tasks in conversation.

Next phases (do not start yet)

  • P2: scripts/new-handoff.ps1 — generate dated handoff from template.
  • P3: Per-project QA scripts (only after repeated pain).
  • P4: AGENTS.md — agent intake protocol.

Promote a phase only when the current one feels insufficient — not on a schedule.

Superseded status (added 2026-05-23): P2 completed same day (new-handoff.ps1 shipped + smoke-tested). P2.5 also shipped (repo-identity contract inline in project YAMLs + playbooks/repo-identity-check.md). P3 and P4 remain deferred per the promotion-ladder rule.