arbor/vision.md

Vision

This product vision builds on the organization manifesto.

Who This Product Serves

Flowmade Developers

The team building Flowmade's platform. They need a git server and product management system that integrates seamlessly with AI-assisted development workflows. Current tools (GitHub, Gitea) weren't designed for how AI changes software development.

Extends: Agencies & Consultancies (from manifesto) - we are our own first customer.

Teams Doing AI-Assisted Development

Development teams using AI coding assistants who need better tooling for tracking work, managing vertical slices, and maintaining context across the development lifecycle.

Extends: Organizations (from manifesto) - they need tools that support their evolving workflows.

What They're Trying to Achieve

These trace back to organization-level jobs:

Product Job	Enables Org Job
"Git hosting that scales horizontally without NFS bottlenecks"	"Delivering solutions faster with maintained quality"
"Track features, milestones, and releases in one place"	"Help me evolve my solutions as my business changes"
"AI assistants understand my issues and can work on them"	"Help me reduce dependency on developers" (AI handles more)
"Full audit trail of every change and decision"	"Adapting solutions as needs evolve" (replay, audit, understand)
"Vertical slices tracked from idea to deployment"	"Software aligned with actual workflows"

The Problem

Current git hosting and issue tracking tools were designed before AI-assisted development:

• Not AI-native. GitHub/Gitea issues are free-form text. AI assistants must scrape and interpret. There's no structured way to express what AI needs to implement a feature.
• Poor scaling story. Self-hosted options (Gitea) don't scale horizontally. Git operations hit NFS bottlenecks. GitLab solved this with Gitaly, but it's complex.
• Siloed concerns. Git hosting, issue tracking, and CI are separate systems with brittle integrations. Context is lost between tools.
• No audit trail. Current state only. Why was this decision made? What changed? Lost to time.

The Solution

Arbor is a Kubernetes-native git server and product management platform built for AI-assisted development:

• Event-sourced metadata. Full audit trail of every change. Issues, PRs, reviews, releases - all events, all history, always.
• Horizontal git scaling. Gitaly-style architecture: dedicated git storage service with gRPC API, sharded by consistent hashing.
• Structured for AI. Issues express what AI needs: acceptance criteria, affected files, dependencies, vertical slice context.
• Unified platform. Git, issues, milestones, releases, CI - one system, one event stream, full context.
• Kubernetes-native. Helm install, horizontal scaling, KEDA-driven CI runners.

Built on Aether for event sourcing and IRIS for UI.

Product Principles

These extend the organization's guiding principles:

AI-First Design

Every feature asks: "How does this help AI assistants do better work?" Issues have structured fields AI can parse. Events provide context AI can understand.

Extends: "AI amplifies individuals" (AI-Augmented Development)

Events as Truth

All metadata is event-sourced. Current state is a projection. History is always available. This directly implements "Auditability by default."

Extends: "Auditability by default" (Architecture Beliefs)

Vertical Slices Over Horizontal Tasks

Work is organized as user-visible value delivery, not technical tasks. Features, not "add persistence layer."

Extends: "Ship to learn" and "Working software over comprehensive documentation"

Kubernetes-Native

Not "runs on Kubernetes" - designed for Kubernetes. StatefulSets for git storage. KEDA for CI scaling. Helm for deployment.

Extends: "Resource Efficiency" - efficient on cloud infrastructure

DDD for the Domain

Repository, PullRequest, Issue, Milestone, Release - real aggregates with business rules. Not CRUD tables.

Extends: "Business language in code" (Architecture Beliefs)

Non-Goals

These extend the organization's non-goals:

• GitHub feature parity. We build what matters for AI-assisted development, not everything GitHub has.
• Generic project management. This is for software development workflows, not arbitrary project tracking.
• Self-contained CI. CI runners are a scaling concern. We provide the queue and coordination, not the execution environment.
• Replacing human judgment. AI assistants work on issues, humans decide what to build.

Architecture

This project follows organization architecture patterns.

Alignment

Belief	Pattern	How Arbor Implements
Auditability by default	Event Sourcing	All metadata is events. Full history for every repo, issue, PR.
Business language in code	DDD	Repository, PullRequest, Issue are aggregates with behavior.
Independent evolution	Event-driven	Components communicate via events. New features subscribe.
Explicit over implicit	Commands and Events	CreateIssue (command) → IssueCreated (event). Intent and outcome distinct.

Bounded Contexts

Context	Aggregates	Responsibility
Repository	Repository, Branch, Commit	Git storage, branches, commits, files
Collaboration	PullRequest, Review, Comment	PRs, reviews, discussions
Planning	Issue, Milestone, Release	Work tracking, product management
Identity	User, Organization, SSHKey	Users, orgs, permissions, keys
CI	Pipeline, Job, Artifact	Runners, jobs, logs, artifacts

Milestones

M1: Git Operations

Users can push, pull, clone repositories via SSH and HTTPS with horizontal scaling.

Success: git clone, git push, git pull work against Arbor with multiple replicas.

M2: Issues and PRs

Users can create issues, open PRs, and conduct reviews with full event history.

Success: Create issue, open PR, merge - all with complete audit trail.

M3: AI Integration

AI assistants can fetch issue context and create PRs programmatically.

Success: Claude Code can /work-issue against an Arbor-hosted repo.

M4: Product Management

Track milestones, releases, and vertical slices with dependency graphs.

Success: /vision and /roadmap commands work against Arbor.