← Back to Kontasks

Unified Turn Start Tool Proposal

Analysis of gvFlow usage and proposal for konui_turn_context unified tool

✓ Completed
on 9 Jan 2026, 8:43 pm

Output

gvFlow Usage Analysis & Unified Tool Proposal

Problem Observed

Claude is NOT calling flow tools despite CLAUDE.md instructions. Evidence:

Active Flow: Johnathon's Session

Title "DASHBOARD CONSOLE REQUEST from user \"johnathon\":"
Turns 37 turns
Linked Kontasks 15 kontasks
Tokens 36.6M tokens

The flow title was never refined - it's just the raw first prompt!

Why Claude Isn't Following Instructions

  1. Multiple tool calls required - Turn start needs 2-3 separate calls
  2. Cognitive load - Easy to skip when focused on user's request
  3. No immediate value visible - Claude doesn't "see" the benefit
  4. Instructions buried - Even with reorganization, it's a lot to remember

Your Idea: Unified Turn Start Tool

Excellent solution! A single tool that returns everything needed:

Proposed: konui_turn_context

// Single call at turn start
const ctx = await konui_turn_context({
  sessionId: "ses_abc123",
  prompt: "User's first message",  // For flow matching
  user: "johnathon"                // For filtering
});

What It Returns:

{
  // Recent kontasks (context recovery)
  "recentKontasks": [
    { id, title, summary, commitSha, filesChanged }
  ],
  
  // Current/matched flow
  "flow": {
    id: "flow_abc",
    title: "Feature: Auth system",
    status: "active",
    matchScore: 0.85,  // If matched from prompt
    kontaskCount: 5,
    decisionCount: 2
  },
  
  // Approved tasks waiting
  "approvedTasks": [
    { id, title, action }
  ],
  
  // Session state
  "session": {
    turnCount: 5,
    fullnessPercent: 42,
    lastCommit: "abc123"
  },
  
  // Git state
  "git": {
    branch: "main",
    uncommittedFiles: 0,
    unpushedCommits: 2
  }
}

Benefits

One call Instead of 2-3 separate tools
Auto flow linking Server-side matching and linking
Rich context Git state, session fullness, approved tasks
Lower token cost Single response vs multiple
Easier compliance Simple instruction: "Call konui_turn_context first"

Implementation Approach

  1. Create konui_turn_context MCP tool
  2. Consolidate logic from existing tools
  3. Add flow auto-matching with prompt analysis
  4. Include git status (already have konui_git_status)
  5. Update CLAUDE.md to just say: "Call konui_turn_context first"

Alternative: Hook-Based Injection

Even simpler - inject context before Claude sees the prompt:

<turn-context>
Recent kontasks: [Session Fullness Indicator] [CLAUDE.md Audit]
Active flow: "Feature: Auth system" (5 kontasks, 2 decisions)
Approved tasks: None
Git: main, clean, 2 unpushed
</turn-context>

User's actual message here...

This requires NO tool call - context injected by konsole automatically.

Recommendation: Implement konui_turn_context first (simpler), then consider hook injection as optimization.

Quick Actions

▶ View Turn
Original Request

No layout configured

Details

Type General
Status Completed
Scope vibetools
Tags gvflowturn-startoptimizationarchitecture
Created 9 Jan 2026, 8:43 pm
Updated 9 Jan 2026, 8:43 pm
Created By claude

📋 Claude's Context

Session ses_d3abe491...

Raw Data

{
  "id": "58a28871-fabd-4ff4-a261-8f63019e5373",
  "type": "general",
  "status": "completed",
  "title": "Unified Turn Start Tool Proposal",
  "description": "Analysis of gvFlow usage and proposal for konui_turn_context unified tool",
  "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;\">gvFlow Usage Analysis & Unified Tool Proposal</h2>\n\n<h3 style=\"font-family:sans-serif;color:#f43f5e;margin:16px 0 8px 0;\">Problem Observed</h3>\n\n<p style=\"line-height:1.6;margin:0 0 12px 0;\">Claude is <strong>NOT</strong> calling flow tools despite CLAUDE.md instructions. Evidence:</p>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h4 style=\"color:#e5c07b;margin:0 0 8px 0;\">Active Flow: Johnathon's Session</h4>\n<table style=\"width:100%;border-collapse:collapse;\">\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:6px;color:#7f848e;\">Title</td>\n<td style=\"padding:6px;color:#f97316;\">\"DASHBOARD CONSOLE REQUEST from user \\\"johnathon\\\":\"</td>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:6px;color:#7f848e;\">Turns</td>\n<td style=\"padding:6px;\">37 turns</td>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:6px;color:#7f848e;\">Linked Kontasks</td>\n<td style=\"padding:6px;\">15 kontasks</td>\n</tr>\n<tr>\n<td style=\"padding:6px;color:#7f848e;\">Tokens</td>\n<td style=\"padding:6px;\">36.6M tokens</td>\n</tr>\n</table>\n<p style=\"color:#f43f5e;margin:12px 0 0 0;\">The flow title was never refined - it's just the raw first prompt!</p>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:16px 0 8px 0;\">Why Claude Isn't Following Instructions</h3>\n\n<ol style=\"margin:0 0 16px 0;line-height:1.8;\">\n<li><span style=\"color:#e5c07b;\">Multiple tool calls required</span> - Turn start needs 2-3 separate calls</li>\n<li><span style=\"color:#e5c07b;\">Cognitive load</span> - Easy to skip when focused on user's request</li>\n<li><span style=\"color:#e5c07b;\">No immediate value visible</span> - Claude doesn't \"see\" the benefit</li>\n<li><span style=\"color:#e5c07b;\">Instructions buried</span> - Even with reorganization, it's a lot to remember</li>\n</ol>\n\n<h3 style=\"font-family:sans-serif;color:#98c379;margin:16px 0 8px 0;\">Your Idea: Unified Turn Start Tool</h3>\n\n<p style=\"line-height:1.6;margin:0 0 12px 0;\"><strong style=\"color:#22c55e;\">Excellent solution!</strong> A single tool that returns everything needed:</p>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h4 style=\"color:#56b6c2;margin:0 0 12px 0;\">Proposed: konui_turn_context</h4>\n<pre style=\"margin:0;color:#98c379;font-size:13px;\">// Single call at turn start\nconst ctx = await konui_turn_context({\n  sessionId: \"ses_abc123\",\n  prompt: \"User's first message\",  // For flow matching\n  user: \"johnathon\"                // For filtering\n});</pre>\n</div>\n\n<h4 style=\"color:#e5c07b;margin:12px 0 8px 0;\">What It Returns:</h4>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"margin:0;color:#e0e0e0;font-size:13px;\">{\n  <span style=\"color:#98c379;\">// Recent kontasks (context recovery)</span>\n  <span style=\"color:#c678dd;\">\"recentKontasks\"</span>: [\n    { id, title, summary, commitSha, filesChanged }\n  ],\n  \n  <span style=\"color:#98c379;\">// Current/matched flow</span>\n  <span style=\"color:#c678dd;\">\"flow\"</span>: {\n    id: \"flow_abc\",\n    title: \"Feature: Auth system\",\n    status: \"active\",\n    matchScore: 0.85,  <span style=\"color:#7f848e;\">// If matched from prompt</span>\n    kontaskCount: 5,\n    decisionCount: 2\n  },\n  \n  <span style=\"color:#98c379;\">// Approved tasks waiting</span>\n  <span style=\"color:#c678dd;\">\"approvedTasks\"</span>: [\n    { id, title, action }\n  ],\n  \n  <span style=\"color:#98c379;\">// Session state</span>\n  <span style=\"color:#c678dd;\">\"session\"</span>: {\n    turnCount: 5,\n    fullnessPercent: 42,\n    lastCommit: \"abc123\"\n  },\n  \n  <span style=\"color:#98c379;\">// Git state</span>\n  <span style=\"color:#c678dd;\">\"git\"</span>: {\n    branch: \"main\",\n    uncommittedFiles: 0,\n    unpushedCommits: 2\n  }\n}</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#c678dd;margin:16px 0 8px 0;\">Benefits</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin-bottom:16px;\">\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;color:#98c379;font-weight:bold;\">One call</td>\n<td style=\"padding:8px;\">Instead of 2-3 separate tools</td>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;color:#98c379;font-weight:bold;\">Auto flow linking</td>\n<td style=\"padding:8px;\">Server-side matching and linking</td>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;color:#98c379;font-weight:bold;\">Rich context</td>\n<td style=\"padding:8px;\">Git state, session fullness, approved tasks</td>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;color:#98c379;font-weight:bold;\">Lower token cost</td>\n<td style=\"padding:8px;\">Single response vs multiple</td>\n</tr>\n<tr>\n<td style=\"padding:8px;color:#98c379;font-weight:bold;\">Easier compliance</td>\n<td style=\"padding:8px;\">Simple instruction: \"Call konui_turn_context first\"</td>\n</tr>\n</table>\n\n<h3 style=\"font-family:sans-serif;color:#f97316;margin:16px 0 8px 0;\">Implementation Approach</h3>\n\n<ol style=\"margin:0 0 16px 0;line-height:1.8;\">\n<li>Create <code style=\"background:#2d2d2d;padding:2px 6px;border-radius:4px;\">konui_turn_context</code> MCP tool</li>\n<li>Consolidate logic from existing tools</li>\n<li>Add flow auto-matching with prompt analysis</li>\n<li>Include git status (already have <code>konui_git_status</code>)</li>\n<li>Update CLAUDE.md to just say: <em>\"Call konui_turn_context first\"</em></li>\n</ol>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:16px 0 8px 0;\">Alternative: Hook-Based Injection</h3>\n\n<p style=\"line-height:1.6;margin:0 0 12px 0;\">Even simpler - inject context <strong>before</strong> Claude sees the prompt:</p>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"margin:0;color:#7f848e;font-size:13px;\"><span style=\"color:#c678dd;\">&lt;turn-context&gt;</span>\nRecent kontasks: [Session Fullness Indicator] [CLAUDE.md Audit]\nActive flow: \"Feature: Auth system\" (5 kontasks, 2 decisions)\nApproved tasks: None\nGit: main, clean, 2 unpushed\n<span style=\"color:#c678dd;\">&lt;/turn-context&gt;</span>\n\n<span style=\"color:#98c379;\">User's actual message here...</span></pre>\n</div>\n\n<p style=\"color:#7f848e;\">This requires NO tool call - context injected by konsole automatically.</p>\n\n<div style=\"margin-top:20px;padding:12px;background:#2d4a2d;border-radius:6px;border-left:4px solid #22c55e;\">\n<strong style=\"color:#22c55e;\">Recommendation:</strong> Implement <code>konui_turn_context</code> first (simpler), then consider hook injection as optimization.\n</div>\n\n</div>",
    "requestedAt": "2026-01-09T00:00:00.000Z",
    "requestId": "a4b4ae4b-a2a6-4f4a-baa6-eb59d9fb55a9",
    "choices": [
      {
        "label": "Implement konui_turn_context",
        "value": "Implement the konui_turn_context MCP tool that consolidates all turn-start information into a single call",
        "primary": true
      },
      {
        "label": "Try hook injection",
        "value": "Implement automatic context injection in konsole before the prompt reaches Claude"
      },
      {
        "label": "Fix current flow",
        "value": "Update the Johnathon flow title to something meaningful and clean up the data"
      }
    ]
  },
  "createdBy": "claude",
  "createdAt": "2026-01-09T10:43:46.744Z",
  "updatedAt": "2026-01-09T10:43:47.022Z",
  "targetUser": "claude",
  "requestId": "a4b4ae4b-a2a6-4f4a-baa6-eb59d9fb55a9",
  "scope": "vibetools",
  "tags": [
    "gvflow",
    "turn-start",
    "optimization",
    "architecture"
  ],
  "sessionId": "ses_d3abe491-395",
  "flowId": "flow_01KEGVRXHHK7E25VFSX4HCV289",
  "flowLinks": [
    {
      "flowId": "flow_01KEGVRXHHK7E25VFSX4HCV289",
      "edgeType": "evidence",
      "createdAt": "2026-01-09T10:43:46.744Z"
    }
  ]
}
DashboardReportsKontasksFlowsDecisionsSessionsTelemetryLogs + Go