SparkClaw — Ürün Yol Haritası

Pazardaki konum, rakip analizi ve farklılaşma silahlarının yazımı.

• T0.1.1

  Vision dokümanı

  docs/00-vision.md — neyi inşa ediyoruz, kimin için, neden şimdi.

• T0.1.2

  Rakip analizi + konumlanma

  docs/01-positioning.md — Dify, Flowise, n8n, ChatGPT GPTs eksenli haritalama.

• T0.1.3

  13-doc serisi

  Mimari, agent network model, capability spec, MCP, co-builder, canvas, runtime, repo, philosophy, glossary, OAuth.

Monorepo, tooling, Docker compose.

• T0.2.1

  pnpm + Turbo monorepo

  apps/ + packages/ + tooling/ yapısı.

• T0.2.2

  TS + Biome + tsconfig presets

  tooling/tsconfig + tooling/biome-config.

• T0.2.3

  Docker compose

  postgres (pgvector) + runtime + builder. Redis placeholder M1b için.

Dark theme tokens + UI primitive kütüphanesi.

• T0.3.1

  Token paleti

  tooling/tailwind-config/tokens.ts — bg/border/text/accent/semantic/node.

• T0.3.2

  UI primitives

  @sparkclaw/ui: Button, Card, Input, Select, IconButton, Tabs, Chip.

ORM seçimi kapatıldı (Drizzle), şema kuruldu.

• T1a.1.1

  agents, usage_events, networks, network_nodes, network_edges şeması

• T1a.1.2

  Drizzle migration runner

  drizzle-kit + tsx ile db:migrate scripti.

• T1a.1.3

  Postgres connection pool

  postgres-js client + graceful shutdown.

API + DB + Mastra Agent cache.

• T1a.2.1

  create / get / list / delete endpoints

  POST/GET/DELETE /v1/agents.

• T1a.2.2

  Mastra Agent process-local cache

  liveAgents map + lazy build.

• T1a.2.3

  Inference provider routing

  MASTRA_GATEWAY_TOKEN veya FAL_KEY, model id normalization.

Case 1 (single chat) + Case 2 (two-agent ping-pong).

• T1a.3.1

  POST /v1/agents/:id/chat

• T1a.3.2

  POST /v1/orchestrate

  Per-agent history isolation; her agent kendi rolünde kalıyor.

• T1a.3.3

  Usage event emission

  Her LLM çağrısında usage_events row.

Üst seviye layout ve navigasyon.

• T1c.1.1

  LeftRail navigation

  Flow / MCPs / Documents / Credentials / Runs / Metrics / Settings.

• T1c.1.2

  ToolsPanel + tools-catalog seed

  AI & Apps + Controls kategorileri.

• T1c.1.3

  CanvasPane (React Flow)

• T1c.1.4

  ConfigPanel (sağ)

Intent → flow-gen / mcp-gen / node-helper alt agentları.

• T1c.2.1

  Intent classifier

  apps/runtime/src/co-builder/intent.ts — 6 niyet sınıfı.

• T1c.2.2

  Flow generator

  NL → {nodes,edges} JSON, doğrudan canvas'a uygulanır.

• T1c.2.3

  MCP generator

  NL → MCP server taslağı (auth, tools, capabilities).

• T1c.2.4

  Node helper

  Seçili node config ince ayar (improve_prompt / node_edit).

• T1c.2.5

  CoBuilderChat bileşeni

  Floating chat — canvas'ın altında.

Üretim seviyesi canvas etkileşimi.

• T1c.3.1

  Custom node tipleri

  Agent / Trigger / Action / Workflow ayrı görünüm.

• T1c.3.2

  Custom edge styles

  static / dynamic / conditional / tool ayrı stil + label.

• T1c.3.3

  Canvas state persistence

  POST /v1/networks ile kayıt, GET ile yükleme.

• T1c.3.4

  Drag-from-panel-to-canvas

  Tool ikonunu canvas'a sürükleyince node oluşur.

• T1c.3.5

  Auto-layout

  Co-builder flow draftında dagre veya elkjs.

Test Run, Publish, capability autocomplete.

• T1c.4.1

  Test Run akışı

  Canvas üstünden "Test Run" → input modal → SSE stream → trace.

• T1c.4.2

  Publish akışı

  Network versiyonlanır, runtime'a deploy edilir.

• T1c.4.3

  Capability autocomplete

  ConfigPanel'de tool seçimi capability spec'ten.

runs / run_steps / run_events tabloları.

• T1b.1.1

  Drizzle şema yazımı

  run kaydı, adım adım state, event stream.

• T1b.1.2

  Migration

@mastra/pg workflow snapshot persistence devreye alınır.

• T1b.2.1

  @mastra/pg storage wiring

• T1b.2.2

  Resume from snapshot

  Server restart sonrası asılı kalan run'lar devam eder.

BullMQ workers; delayed jobs, retry, DLQ.

• T1b.3.1

  docker-compose Redis activate

• T1b.3.2

  BullMQ kurulumu + queue başına worker

• T1b.3.3

  Exponential backoff + DLQ

• T1b.3.4

  Idempotency key per step

Browser bağlanıp run'ı baştan veya offset'ten dinleyebilir.

• T1b.4.1

  GET /v1/runs/:id/events (SSE)

• T1b.4.2

  Resume header (Last-Event-ID)

• T1b.4.3

  Builder client (useChat)

LeftRail "Runs" navigasyonundaki gerçek sayfa.

• T1b.5.1

  Run listesi

  Filter: status, workspace, agent.

• T1b.5.2

  Run detay timeline

  Adım adım expand edilebilir.

• T1b.5.3

  "Re-run from step" affordance

Mastra MCPClient runtime entegrasyonu.

• T2.1.1

  MCPClient wiring (stdio + HTTP + SSE)

• T2.1.2

  MCP server lifecycle

  start/stop/health/restart-on-crash.

• T2.1.3

  Tool catalog dynamic load

  Aktif MCP'lerin tool'ları registry'de listelenir.

mcp_servers + mcp_tools + mcp_capabilities tabloları.

• T2.2.1

  Drizzle şema

• T2.2.2

  GET /v1/mcps + /v1/mcps/:id/tools

• T2.2.3

  Tools panel — gerçek registry verisi

  tools-catalog.ts statik seed yerine API.

• T2.2.4

  MCP install/uninstall UI

Açık standart: domain.verb-noun manifest'leri.

• T2.3.1

  JSON Schema spec

  packages/capability-spec/schema/capability.schema.json.

• T2.3.2

  İlk 25 manifest

  messaging, issue-tracking, version-control, error-monitoring, web, llm, code-execution, voice, vision, email, calendar, storage, db.

• T2.3.3

  Validation runtime

  @sparkclaw/capability-spec içinde Zod + ajv.

• T2.3.4

  /.well-known/capabilities.json endpoint

  MCP self-declare protokolü.

• T2.3.5

  output_projection alanı

  Tool sonucu kompaktlama spec'te.

packages/mcp-authoring/src/wrapper.ts — API'si olan her servisi MCP yapar.

• T2.4.1

  OpenAPI 3.1 parser

• T2.4.2

  Operation → tool synthesis

• T2.4.3

  Auth mapping (api_key / oauth2 / bearer)

• T2.4.4

  In-process MCP module generator

  Mastra tool seti olarak; subprocess gerekmez.

• T2.4.5

  Manual spec (OpenAPI yoksa)

  Co-builder mcp-generator'ın çıktısını runnable hale getirir.

Day-1 demo değerini taşıyan 5-7 MCP.

• T2.5.1

  YouTube MCP

  Adopt or wrap; Google OAuth + API key option.

• T2.5.2

  X (Twitter) MCP

  OAuth 2.0 PKCE + paid tier handling.

• T2.5.3

  Slack MCP

• T2.5.4

  GitHub MCP

• T2.5.5

  Google Drive / Sheets / Docs

• T2.5.6

  Notion MCP

docs/13 — multi-tenant credential katmanı.

• T2.6.1

  OAuth provider config schema

  client_id/secret/scopes/auth_url/token_url.

• T2.6.2

  /oauth/start/:provider + /oauth/callback/:provider

  PKCE + state param + redirect.

• T2.6.3

  oauth_credentials tablo + envelope encryption

• T2.6.4

  Token refresh scheduler

  Pre-emptive 10 dk önce refresh.

• T2.6.5

  Credential injection to MCP env/headers

• T2.6.6

  Credentials sayfası UI

  Connect / Reconnect / Revoke butonları.

User-authored MCP'ler için izolasyon. Dify-tarzı isolated-vm yaklaşımı tier 1.

• T2.7.1

  isolated-vm prototype

• T2.7.2

  User-MCP loader

  Module load + capability check + memory cap.

• T2.7.3

  Resource limits (CPU/mem/network)

• T2.7.4

  Egress firewall (allowlist)

Capability spec'teki output_projection'ın runtime tarafı.

• T2.8.1

  Projector implementasyonu

  packages/agent-core/src/projection.ts.

• T2.8.2

  "detail on demand" tool variant

  İkinci tool call ile derin sonuç.

• T2.8.3

  Cost ölçümü — projeksiyon öncesi/sonrası

User + session.

• T3.1.1

  Auth provider seçimi

  Clerk / WorkOS / kendi? Açık karar.

• T3.1.2

  users + sessions + api_keys tabloları

• T3.1.3

  Login + signup UI

• T3.1.4

  Hono auth middleware

Tek-tenant → multi-tenant geçiş.

• T3.2.1

  workspaces + workspace_members şeması

• T3.2.2

  Default workspace on signup

• T3.2.3

  Workspace switcher UI

• T3.2.4

  Invite + role management

  admin / editor / viewer.

Postgres RLS — cross-tenant leak garanti edilir.

• T3.3.1

  Tüm workspace-scoped tablolarda RLS policy

• T3.3.2

  SET app.workspace_id middleware

• T3.3.3

  Cross-tenant leak test suite

Mastra Memory entegrasyonu + policy.

• T3.4.1

  Mastra Memory wiring

• T3.4.2

  Working memory schema (user prefs)

• T3.4.3

  Semantic recall

• T3.4.4

  Observational memory (Observer/Reflector)

• T3.4.5

  Memory write policy

  Tool result memory'e DEĞİL, sadece insight'lar.

Custom corpus için — kullanıcı PDF/Notion yükler.

• T3.5.1

  @mastra/rag + PgVector

• T3.5.2

  Document upload UI

• T3.5.3

  Chunking + embedding pipeline

• T3.5.4

  Hybrid search (BM25 + vector)

• T3.5.5

  Re-ranking (Cohere Rerank veya cross-encoder)

• T3.5.6

  Incremental re-indexing (cron + diff)

SOC 2 ön-koşulu.

• T3.6.1

  audit_events şeması

  who / what / when / target / metadata.

• T3.6.2

  Audit middleware (sensitive actions)

• T3.6.3

  Audit timeline UI

docs/03 edge tiplerinin runtime implementasyonu.

• T4.1.1

  Network DAG resolver

• T4.1.2

  Static handoff edge

• T4.1.3

  Dynamic handoff (LLM-routed)

• T4.1.4

  Conditional handoff

• T4.1.5

  Agent-as-tool edge

• T4.1.6

  Concurrent fan-out + join

Webhook / cron / event / manual.

• T4.2.1

  Webhook receiver + HMAC verification

• T4.2.2

  Cron scheduler (BullMQ repeat)

• T4.2.3

  Event trigger (event bus → run)

• T4.2.4

  Manual trigger (test-run)

docs/11 #3 açık karar — Redis Streams ile başla.

• T4.3.1

  Karar: Redis Streams vs NATS vs Inngest

• T4.3.2

  Topic/consumer-group şeması

• T4.3.3

  Event emit API (agents + MCPs)

Multi-step flow rollback.

• T4.4.1

  Compensation step schema

  Capability spec'te idempotent + reverses alanları.

• T4.4.2

  Rollback executor

Handoff sırasında ne aktarılır — context engineering politikası.

• T4.5.1

  Edge context policy

  static = full / dynamic = summary / conditional = filtered / tool = args.

• T4.5.2

  Prompt assembler

  packages/agent-core/src/prompt-assembler.ts — stable-prefix order.

• T4.5.3

  Prompt caching wiring (Anthropic cache_control)

Endüstri standardı tracing.

• T5.1.1

  OTel SDK setup

• T5.1.2

  Hono instrumentation

• T5.1.3

  Mastra trace bridge

• T5.1.4

  OTLP exporter (Tempo/Honeycomb/Jaeger)

Generic OTel'in yakalayamadığı detaylar.

• T5.2.1

  Trace store (Langfuse veya Postgres)

• T5.2.2

  Prompt + completion capture

• T5.2.3

  Tool call args/results capture

• T5.2.4

  Cache hit/miss visibility

Builder içinde adım adım izleme.

• T5.3.1

  Trace timeline bileşeni

• T5.3.2

  Step expand → prompt/response panel

• T5.3.3

  "Re-run from step" interactive

usage_events üstüne rollup.

• T5.4.1

  Pricing tablosu

  Provider × model × token tipi × cache discount.

• T5.4.2

  Günlük/haftalık rollup

• T5.4.3

  Per-agent / per-workspace breakdown

• T5.4.4

  Cost alarmları (threshold uyarısı)

pino + correlation IDs.

• T5.5.1

  pino structured logging

• T5.5.2

  Correlation ID propagation

• T5.5.3

  Log levels by env

Mastra Evals üstüne katman.

• T6.1.1

  Eval scenarios schema

• T6.1.2

  LLM-as-judge graders

• T6.1.3

  Code-based graders (exact / regex / JSON Schema)

• T6.1.4

  Dataset versioning

Suite oluştur, koş, fark gör.

• T6.2.1

  Eval suite listesi

• T6.2.2

  Eval run + tarih

• T6.2.3

  Regression diff

  passing → failing scenarios highlight.

Input/output filtreleri.

• T6.3.1

  Prompt injection detection

• T6.3.2

  PII / secrets output filter

• T6.3.3

  Topic constraint enforcement

Network kopyalanır; upstream lineage saklanır.

• T7.1.1

  Network version metadata

• T7.1.2

  Fork action (copy + lineage)

• T7.1.3

  Immutable upstream guard

Upstream güncellense fork'un haber alır.

• T7.2.1

  Diff against upstream

• T7.2.2

  Manual merge UI

Public network listing.

• T7.3.1

  Publish action (visibility flag)

• T7.3.2

  Marketplace search

• T7.3.3

  Trust signals (verified / install count)

docs/11 #14 açık karar.

• T7.4.1

  Moderation queue

• T7.4.2

  Take-down policy

• T7.4.3

  Verified vendor program

Metered subscriptions.

• T8.1.1

  Stripe Connect + metered subscription

• T8.1.2

  usage_events → Stripe usage record sync

• T8.1.3

  Plan tiers (free / pro / team / enterprise)

• T8.1.4

  Invoice + receipt UI

Markup model + per-user breakdown.

• T8.2.1

  Workspace cost rollup (markup_usd_micro)

• T8.2.2

  Per-user cost (within workspace)

• T8.2.3

  Nested LLM call attribution

  docs/11 #16 açık.

SOC 2 + GDPR.

• T8.3.1

  SOC 2 Type II prep

  Controls + Vanta/Drata.

• T8.3.2

  GDPR data subject rights (export + erasure)

• T8.3.3

  Data residency option (EU / US)

• T8.3.4

  DPA template

Multi-stage Docker, cloud target.

• T9.1.1

  Multi-stage Dockerfile prod-ready (Turbo prune)

• T9.1.2

  Runtime cloud deploy (Railway/Fly)

• T9.1.3

  Builder Vercel deploy

• T9.1.4

  Helm chart (self-host)

Zero-downtime garanti.

• T9.2.1

  Expand-contract playbook

• T9.2.2

  Migration CI gate (test + dry-run)

Sentry + uptime + healthcheck.

• T9.3.1

  Sentry error tracking

• T9.3.2

  Uptime monitor (BetterStack/Healthchecks.io)

• T9.3.3

  Healthcheck discovery (docker + cloud)

Public docs + API reference.

• T9.4.1

  apps/docs (Nextra veya Fumadocs)

• T9.4.2

  API reference (OpenAPI sourced)

• T9.4.3

  Co-builder agent yazma rehberi

• T9.4.4

  MCP yazma rehberi

Public TypeScript SDK.

• T9.5.1

  packages/sdk boilerplate

• T9.5.2

  OpenAPI'den auto-generated client

• T9.5.3

  npm publish