← Back to Kontasks

gvGraph Schema Design Complete

Created /gv/docs/gvGraphSchema.md defining kontask-flow graph relationships

✓ Completed
on 9 Jan 2026, 4:39 pm

Output

Graph Schema Created

Commit eb5f7076

/gv/docs/gvGraphSchema.md

630 lines defining the full graph model for kontask-flow relationships.

Edge Types Defined

Type Direction Meaning
genesis kontask → flow Kontask approval created the flow
evidence kontask → flow Kontask documents work done in flow
decision kontask → flow Kontask captured a design decision
output kontask → flow Kontask is flow's deliverable
spawned flow → kontask Flow's work produced this kontask
reference kontask → flow Informational link (no work)

Schema Extensions

// TaskContext additions
flowLinks?: KontaskFlowLink[];  // Many-to-many edges
turnId?: string;              // Source turn
sessionId?: string;           // Source session
spawnedFlowId?: string;       // If genesis

// GvFlow additions
kontaskLinks?: FlowKontaskLink[];
genesisKontaskId?: string;
kontaskIds?: string[];        // Denormalized

Junction Entity: GvEdge

interface GvEdge {
  id: string;                // "edge_{ulid}"
  sourceType: "kontask" | "flow" | ...;
  sourceId: string;
  targetType: "kontask" | "flow" | ...;
  targetId: string;
  edgeType: EdgeType;
  createdAt: string;
  createdBy: { agent, userId?, turnId? };
  reason?: string;
}

Migration Path

  1. Phase 1: Schema extension (add optional fields) - Non-breaking
  2. Phase 2: Auto-linking (create edges on kontask creation)
  3. Phase 3: Junction table (gvedges.jsonl, indexes)
  4. Phase 4: UI integration (badges, graph viz)

New MCP Tools Proposed

konui_link_kontask_to_flow({ kontaskId, flowId, edgeType })
konui_get_flow_kontasks({ flowId, edgeTypes? })
konui_get_kontask_flows({ kontaskId, edgeTypes? })
konui_get_flow_graph({ flowId, includeKontasks?, ... })

Key Insight Captured

Flows are a directed graph, not a hierarchy. A kontask can contribute to multiple flows. A flow accumulates evidence from many kontasks. The genesis edge tracks what spawned what.

Quick Actions

Original Request

No layout configured

Details

Type General
Status Completed
Scope vibetools
Tags gvflowskontasksarchitectureschema
Created 9 Jan 2026, 4:39 pm
Updated 9 Jan 2026, 4:39 pm
Timing
⏱️ 167.6s
0 tools
● TTFE 0% ● Thinking 100% ● Tools 0%
Created By claude

🔗 Git Commit

eb5f7076

Raw Data

{
  "id": "b0259818-5144-47a2-8a84-a8b87d7a9a2e",
  "type": "general",
  "status": "completed",
  "title": "gvGraph Schema Design Complete",
  "description": "Created /gv/docs/gvGraphSchema.md defining kontask-flow graph relationships",
  "context": {
    "output": "<div style=\"background:#1e1e1e;color:#e0e0e0;padding:20px;border-radius:8px;font-family:'Consolas','Monaco',monospace;\">\n<h2 style=\"font-family:sans-serif;color:#fff;margin:0 0 16px 0;\">Graph Schema Created</h2>\n<p style=\"color:#7f848e;margin-bottom:16px;\">Commit <code style=\"background:#2d2d2d;padding:2px 6px;border-radius:3px;color:#98c379;\">eb5f7076</code></p>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#61afef;margin:0 0 12px 0;\">/gv/docs/gvGraphSchema.md</h3>\n<p style=\"color:#e0e0e0;line-height:1.6;margin:0;\">630 lines defining the full graph model for kontask-flow relationships.</p>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#22c55e;margin:0 0 12px 0;\">Edge Types Defined</h3>\n<table style=\"width:100%;font-size:12px;border-collapse:collapse;\">\n<tr style=\"border-bottom:1px solid #444;\">\n<th style=\"color:#7f848e;text-align:left;padding:8px 4px;\">Type</th>\n<th style=\"color:#7f848e;text-align:left;padding:8px 4px;\">Direction</th>\n<th style=\"color:#7f848e;text-align:left;padding:8px 4px;\">Meaning</th>\n</tr>\n<tr style=\"border-bottom:1px solid #333;\">\n<td style=\"padding:8px 4px;\"><span style=\"color:#22c55e;\">genesis</span></td>\n<td style=\"color:#e0e0e0;\">kontask → flow</td>\n<td style=\"color:#7f848e;\">Kontask approval created the flow</td>\n</tr>\n<tr style=\"border-bottom:1px solid #333;\">\n<td style=\"padding:8px 4px;\"><span style=\"color:#61afef;\">evidence</span></td>\n<td style=\"color:#e0e0e0;\">kontask → flow</td>\n<td style=\"color:#7f848e;\">Kontask documents work done in flow</td>\n</tr>\n<tr style=\"border-bottom:1px solid #333;\">\n<td style=\"padding:8px 4px;\"><span style=\"color:#c678dd;\">decision</span></td>\n<td style=\"color:#e0e0e0;\">kontask → flow</td>\n<td style=\"color:#7f848e;\">Kontask captured a design decision</td>\n</tr>\n<tr style=\"border-bottom:1px solid #333;\">\n<td style=\"padding:8px 4px;\"><span style=\"color:#f59e0b;\">output</span></td>\n<td style=\"color:#e0e0e0;\">kontask → flow</td>\n<td style=\"color:#7f848e;\">Kontask is flow's deliverable</td>\n</tr>\n<tr style=\"border-bottom:1px solid #333;\">\n<td style=\"padding:8px 4px;\"><span style=\"color:#e5c07b;\">spawned</span></td>\n<td style=\"color:#e0e0e0;\">flow → kontask</td>\n<td style=\"color:#7f848e;\">Flow's work produced this kontask</td>\n</tr>\n<tr>\n<td style=\"padding:8px 4px;\"><span style=\"color:#7f848e;\">reference</span></td>\n<td style=\"color:#e0e0e0;\">kontask → flow</td>\n<td style=\"color:#7f848e;\">Informational link (no work)</td>\n</tr>\n</table>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#c678dd;margin:0 0 12px 0;\">Schema Extensions</h3>\n<pre style=\"background:#1e1e1e;padding:12px;border-radius:4px;margin:0;font-size:11px;overflow-x:auto;line-height:1.8;\">\n<span style=\"color:#7f848e;\">// TaskContext additions</span>\n<span style=\"color:#98c379;\">flowLinks?</span>: KontaskFlowLink[];  <span style=\"color:#7f848e;\">// Many-to-many edges</span>\n<span style=\"color:#98c379;\">turnId?</span>: string;              <span style=\"color:#7f848e;\">// Source turn</span>\n<span style=\"color:#98c379;\">sessionId?</span>: string;           <span style=\"color:#7f848e;\">// Source session</span>\n<span style=\"color:#98c379;\">spawnedFlowId?</span>: string;       <span style=\"color:#7f848e;\">// If genesis</span>\n\n<span style=\"color:#7f848e;\">// GvFlow additions</span>\n<span style=\"color:#98c379;\">kontaskLinks?</span>: FlowKontaskLink[];\n<span style=\"color:#98c379;\">genesisKontaskId?</span>: string;\n<span style=\"color:#98c379;\">kontaskIds?</span>: string[];        <span style=\"color:#7f848e;\">// Denormalized</span>\n</pre>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#f43f5e;margin:0 0 12px 0;\">Junction Entity: GvEdge</h3>\n<pre style=\"background:#1e1e1e;padding:12px;border-radius:4px;margin:0;font-size:11px;overflow-x:auto;line-height:1.8;\">\n<span style=\"color:#c678dd;\">interface</span> <span style=\"color:#e5c07b;\">GvEdge</span> {\n  id: string;                <span style=\"color:#7f848e;\">// \"edge_{ulid}\"</span>\n  sourceType: <span style=\"color:#98c379;\">\"kontask\"</span> | <span style=\"color:#98c379;\">\"flow\"</span> | ...;\n  sourceId: string;\n  targetType: <span style=\"color:#98c379;\">\"kontask\"</span> | <span style=\"color:#98c379;\">\"flow\"</span> | ...;\n  targetId: string;\n  edgeType: EdgeType;\n  createdAt: string;\n  createdBy: { agent, userId?, turnId? };\n  reason?: string;\n}\n</pre>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#56b6c2;margin:0 0 12px 0;\">Migration Path</h3>\n<ol style=\"color:#e0e0e0;margin:0;padding-left:20px;line-height:1.8;font-size:13px;\">\n<li><strong style=\"color:#fff;\">Phase 1:</strong> Schema extension (add optional fields) - <span style=\"color:#22c55e;\">Non-breaking</span></li>\n<li><strong style=\"color:#fff;\">Phase 2:</strong> Auto-linking (create edges on kontask creation)</li>\n<li><strong style=\"color:#fff;\">Phase 3:</strong> Junction table (gvedges.jsonl, indexes)</li>\n<li><strong style=\"color:#fff;\">Phase 4:</strong> UI integration (badges, graph viz)</li>\n</ol>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#e5c07b;margin:0 0 12px 0;\">New MCP Tools Proposed</h3>\n<pre style=\"background:#1e1e1e;padding:12px;border-radius:4px;margin:0;font-size:11px;overflow-x:auto;\">\nkonui_link_kontask_to_flow({ kontaskId, flowId, edgeType })\nkonui_get_flow_kontasks({ flowId, edgeTypes? })\nkonui_get_kontask_flows({ kontaskId, edgeTypes? })\nkonui_get_flow_graph({ flowId, includeKontasks?, ... })\n</pre>\n</div>\n\n<div style=\"background:#1e1e1e;border:1px solid #22c55e;padding:12px;border-radius:6px;\">\n<h4 style=\"color:#22c55e;margin:0 0 8px 0;\">Key Insight Captured</h4>\n<p style=\"color:#e0e0e0;margin:0;font-size:13px;\">Flows are a <strong style=\"color:#c678dd;\">directed graph</strong>, not a hierarchy. A kontask can contribute to multiple flows. A flow accumulates evidence from many kontasks. The genesis edge tracks what spawned what.</p>\n</div>\n</div>",
    "requestedAt": "2026-01-09T06:35:00.000Z",
    "requestId": "a90d6ab7-0c2b-4e6b-9dd4-dfcf3a3818e5",
    "commitSha": "eb5f7076",
    "choices": [
      {
        "label": "Start Phase 1",
        "value": "Implement Phase 1 - add the optional flowLinks field to TaskContext and kontaskIds to GvFlow",
        "primary": true
      },
      {
        "label": "Review Schema",
        "value": "Read the full gvGraphSchema.md document and give me feedback"
      },
      {
        "label": "Discuss First",
        "value": "I have questions about the schema design before we implement"
      }
    ],
    "turnTiming": {
      "totalMs": 167599,
      "ttfeMs": 101,
      "thinkingMs": 167498,
      "toolExecutionMs": 0,
      "toolCallCount": 0,
      "thinkingPct": 100,
      "toolsPct": 0,
      "ttfePct": 0
    }
  },
  "createdBy": "claude",
  "createdAt": "2026-01-09T06:39:02.594Z",
  "updatedAt": "2026-01-09T06:39:07.380Z",
  "requestId": "a90d6ab7-0c2b-4e6b-9dd4-dfcf3a3818e5",
  "scope": "vibetools",
  "tags": [
    "gvflows",
    "kontasks",
    "architecture",
    "schema"
  ],
  "targetUser": "claude"
}
DashboardReportsKontasksFlowsDecisionsSessionsTelemetryLogs + Go