lynkr 3.2.1 → 4.0.0

package/docs/GSD_LEARNINGS.md

@@ -0,0 +1,1116 @@
+# Learnings from GET SHIT DONE Repository
+
+**Source:** https://github.com/glittercowboy/get-shit-done
+**Analyzed:** 2026-01-11
+**Stars:** 1.4k | **Forks:** 191
+
+---
+
+## Executive Summary
+
+GET SHIT DONE (GSD) is a meta-prompting system for Claude Code that prevents quality degradation through structured workflows and fresh context management. Key innovation: **breaking work into atomic tasks executed by fresh subagents** rather than long single-session conversations.
+
+**What Lynkr does better:**
+- ✅ Multi-provider support (9 providers vs Claude-only)
+- ✅ Token optimization (60-80% reduction via caching, tool selection)
+- ✅ IDE integration (Cursor support, OpenAI API compatibility)
+- ✅ Hybrid routing (local + cloud fallback)
+
+**What GSD does better:**
+- ✅ Context management (fresh agents per task)
+- ✅ Atomic task planning (enforced 2-3 task breakdown)
+- ✅ Codebase mapping (7-document parallel analysis)
+- ✅ Git integration (automatic commits per task)
+
+---
+
+## Key Patterns & Missing Features
+
+### 1. Fresh Context Per Task (Multi-Agent Pattern)
+
+#### Problem Statement
+**Current behavior in Lynkr:**
+- Single session conversation grows indefinitely
+- As context fills (150k+ tokens), quality degrades
+- Claude starts saying "Due to context limits, I'll be more concise..."
+- User must manually start new session
+
+**GSD's solution:**
+- Each task spawns fresh subagent with 200k clean tokens
+- Essential state passed as summary
+- Prevents context pollution
+- Maintains consistent quality
+
+#### Implementation Plan
+
+**Files to modify:**
+- `src/orchestrator/index.js` - Add context monitoring
+- `src/agents/index.js` - Add task-based spawning
+- `src/config/index.js` - Add context thresholds
+
+**Configuration additions:**
+```javascript
+// .env
+CONTEXT_BUDGET_WARNING=150000      # Warn at 150k tokens
+CONTEXT_BUDGET_MAX=180000          # Hard limit at 180k tokens
+AUTO_SPAWN_SUBAGENT=false          # Auto-spawn when hitting limit (default: false)
+SUBAGENT_CONTEXT_SUMMARY_LENGTH=5000  # Summary size for new agent
+```
+
+**Code implementation:**
+```javascript
+// src/orchestrator/index.js (after line 1500)
+
+async function checkContextBudget(session, estimatedTokens) {
+  const warningThreshold = config.CONTEXT_BUDGET_WARNING || 150000;
+  const maxThreshold = config.CONTEXT_BUDGET_MAX || 180000;
+
+  if (estimatedTokens > warningThreshold) {
+    const utilization = Math.round(estimatedTokens / maxThreshold * 100);
+
+    logger.warn({
+      estimatedTokens,
+      warningThreshold,
+      maxThreshold,
+      utilization: `${utilization}%`
+    }, "⚠️  Context approaching budget limit");
+
+    // Option A: Auto-spawn (aggressive)
+    if (config.AUTO_SPAWN_SUBAGENT && estimatedTokens > maxThreshold) {
+      return await spawnFreshSubagent(session);
+    }
+
+    // Option B: Inject warning (conservative)
+    return {
+      warning: true,
+      message: `Context budget at ${utilization}%. Consider:
+        1. Breaking current task into smaller subtasks
+        2. Completing current work before starting new tasks
+        3. Starting fresh session for complex work`
+    };
+  }
+
+  return { warning: false };
+}
+
+async function spawnFreshSubagent(session) {
+  const summary = await summarizeSessionState(session, {
+    maxLength: config.SUBAGENT_CONTEXT_SUMMARY_LENGTH || 5000,
+    include: {
+      currentTask: true,
+      recentDecisions: true,
+      activeFiles: true,
+      blockers: true
+    }
+  });
+
+  logger.info({
+    parentSession: session.id,
+    summaryTokens: summary.tokens
+  }, "Spawning fresh subagent with summarized context");
+
+  const { executeAgent } = require("./agents");
+  return await executeAgent({
+    agentType: "general-purpose",
+    task: summary.currentTask,
+    context: summary.text,
+    maxSteps: 15,
+    parentSession: session.id
+  });
+}
+
+function summarizeSessionState(session, options = {}) {
+  const recentTurns = session.messages.slice(-10); // Last 10 turns
+  const currentFiles = extractActiveFiles(session.messages);
+  const decisions = extractDecisions(session.messages);
+  const blockers = extractBlockers(session.messages);
+
+  const summary = `
+<session-summary>
+  <current-task>
+    ${extractCurrentTask(recentTurns)}
+  </current-task>
+
+  <active-files>
+    ${currentFiles.map(f => `<file>${f}</file>`).join('\n    ')}
+  </active-files>
+
+  <recent-decisions>
+    ${decisions.map(d => `<decision>${d}</decision>`).join('\n    ')}
+  </recent-decisions>
+
+  <blockers>
+    ${blockers.map(b => `<blocker>${b}</blocker>`).join('\n    ')}
+  </blockers>
+
+  <next-steps>
+    ${suggestNextSteps(recentTurns)}
+  </next-steps>
+</session-summary>`;
+
+  return {
+    text: summary,
+    tokens: estimateTokens(summary)
+  };
+}
+```
+
+**Priority:** HIGH
+**Difficulty:** 5/10 (medium)
+**Effort:** 4-6 hours
+**Value:** Prevents quality degradation in long sessions
+
+---
+
+### 2. Atomic Task Planning (Enforced Breakdown)
+
+#### Problem Statement
+**Current behavior in Lynkr:**
+- TodoWrite tool exists but not enforced
+- Users can request complex multi-step tasks
+- No automatic breakdown into atomic units
+- No verification of task completeness
+
+**GSD's solution:**
+- Enforces 2-3 task maximum per phase
+- Each task has clear completion criteria
+- Tasks are atomic (single focus, discrete)
+- XML-structured for precision
+
+#### Implementation Plan
+
+**Files to modify:**
+- `src/orchestrator/index.js` - Add task complexity detection
+- `src/utils/task-planner.js` - New file for atomic planning
+- `src/prompts/task-breakdown.js` - Task breakdown prompt
+
+**Code implementation:**
+```javascript
+// src/utils/task-planner.js (NEW FILE)
+
+const logger = require("../logger");
+const { estimateTokenCount } = require("./tokens");
+
+/**
+ * Detect if user request is complex and needs breakdown
+ */
+function isComplexTask(userMessage) {
+  const complexityIndicators = [
+    // Multiple verbs
+    /\b(and|then|also|after|before)\b/gi,
+    // Multiple files mentioned
+    /\b(file|files|folder|folders|directory|directories)\b.*\b(file|files|folder|folders|directory|directories)\b/gi,
+    // Multiple actions
+    /\b(create|add|update|fix|refactor|implement|write)\b.*\b(create|add|update|fix|refactor|implement|write)\b/gi,
+    // Long descriptions (>200 words)
+    userMessage.split(/\s+/).length > 200,
+    // Multiple features/components
+    /\b(feature|component|module|service)\b.*\b(feature|component|module|service)\b/gi
+  ];
+
+  return complexityIndicators.some(indicator =>
+    typeof indicator === 'boolean' ? indicator : indicator.test(userMessage)
+  );
+}
+
+/**
+ * Generate atomic task breakdown using LLM
+ */
+async function generateAtomicTasks(userMessage, context = {}) {
+  const prompt = `
+<task-breakdown-request>
+  <user-request>
+    ${userMessage}
+  </user-request>
+
+  <context>
+    <current-files>
+      ${context.files?.join(', ') || 'Unknown'}
+    </current-files>
+    <tech-stack>
+      ${context.stack || 'Unknown'}
+    </tech-stack>
+  </context>
+
+  <instructions>
+    Break down the user's request into atomic tasks following these rules:
+
+    1. Each task must be ATOMIC (single focus, discrete action)
+    2. Maximum 2-3 tasks per phase
+    3. If more than 3 tasks needed, create multiple phases
+    4. Each task must have:
+       - Clear name (verb + object, e.g., "Add authentication middleware")
+       - Specific files to modify
+       - Concrete action description
+       - Verification steps
+       - Completion criteria
+
+    Return in XML format:
+    <task-plan>
+      <phase name="Phase 1 Name">
+        <task>
+          <name>Task name</name>
+          <files>file1.js, file2.js</files>
+          <action>What to do</action>
+          <verify>How to verify</verify>
+          <done>Completion criteria</done>
+        </task>
+      </phase>
+    </task-plan>
+  </instructions>
+</task-breakdown-request>`;
+
+  // Call LLM to generate plan (use fast model like Haiku)
+  const response = await invokeModel({
+    model: "haiku", // Fast, cheap for planning
+    messages: [{ role: "user", content: prompt }],
+    max_tokens: 2000
+  });
+
+  return parseTaskPlan(response.content);
+}
+
+function parseTaskPlan(xmlContent) {
+  // Parse XML into structured task plan
+  // Returns: { phases: [{ name, tasks: [{ name, files, action, verify, done }] }] }
+  // Implementation uses XML parser or regex extraction
+}
+
+module.exports = {
+  isComplexTask,
+  generateAtomicTasks
+};
+```
+
+**Integration in orchestrator:**
+```javascript
+// src/orchestrator/index.js
+
+const { isComplexTask, generateAtomicTasks } = require("../utils/task-planner");
+
+async function processMessage({ payload, headers, session, options }) {
+  const userMessage = payload.messages[payload.messages.length - 1].content;
+
+  // Check if task is complex
+  if (isComplexTask(userMessage)) {
+    logger.info("Detected complex task, suggesting atomic breakdown");
+
+    // Generate task plan
+    const taskPlan = await generateAtomicTasks(userMessage, {
+      files: extractFilesFromContext(session),
+      stack: detectTechStack(session)
+    });
+
+    // Present to user for approval
+    const approval = await askUserApproval({
+      message: "This looks complex! I suggest breaking it into these atomic tasks:",
+      plan: taskPlan,
+      options: [
+        { label: "Approve & execute", value: "approve" },
+        { label: "Modify plan", value: "modify" },
+        { label: "Execute without planning", value: "skip" }
+      ]
+    });
+
+    if (approval === "approve") {
+      // Execute tasks one by one with fresh context
+      return await executeAtomicTasks(taskPlan, session);
+    }
+  }
+
+  // Continue with normal execution
+  // ...
+}
+```
+
+**Priority:** MEDIUM
+**Difficulty:** 6/10 (medium-high)
+**Effort:** 6-8 hours
+**Value:** Improves success rate for complex requests
+
+---
+
+### 3. XML-Structured Prompts (Better Parsing)
+
+#### Problem Statement
+**Current behavior in Lynkr:**
+- All tool parameters use JSON
+- Natural language instructions in system prompts
+- Can be ambiguous with nested structures
+
+**GSD's solution:**
+- Uses XML for semantic structure
+- Claude parses XML more reliably than JSON
+- Tags provide meaning (e.g., `<verify>`, `<done>`)
+
+#### Implementation Plan
+
+**Use cases for XML in Lynkr:**
+1. Complex tool calls with nested parameters
+2. Task definitions in TodoWrite
+3. Memory injection format
+4. State summaries for subagents
+
+**Example conversion:**
+
+**Current (JSON):**
+```json
+{
+  "todos": [
+    {
+      "content": "Add authentication",
+      "status": "pending",
+      "activeForm": "Adding authentication"
+    }
+  ]
+}
+```
+
+**Proposed (XML):**
+```xml
+<todos>
+  <todo status="pending">
+    <content>Add authentication</content>
+    <activeForm>Adding authentication</activeForm>
+    <verify>User can login with valid credentials</verify>
+    <done>Tests pass and token is returned</done>
+  </todo>
+</todos>
+```
+
+**Configuration:**
+```javascript
+// .env
+PROMPT_FORMAT=json  # Options: json, xml (default: json)
+```
+
+**Implementation:**
+```javascript
+// src/utils/prompt-format.js (NEW FILE)
+
+function formatToolCall(toolName, params, format = "json") {
+  if (format === "xml") {
+    return formatToolCallXML(toolName, params);
+  }
+  return formatToolCallJSON(toolName, params);
+}
+
+function formatToolCallXML(toolName, params) {
+  const xmlParams = Object.entries(params)
+    .map(([key, value]) => {
+      if (Array.isArray(value)) {
+        return `<${key}>\n${value.map(item => formatXMLItem(key, item)).join('\n')}\n</${key}>`;
+      }
+      return `<${key}>${escapeXML(value)}</${key}>`;
+    })
+    .join('\n  ');
+
+  return `<tool name="${toolName}">
+  ${xmlParams}
+</tool>`;
+}
+
+function parseToolResponseXML(xmlString) {
+  // Parse XML response back to structured data
+  // Uses fast-xml-parser or similar
+}
+```
+
+**Priority:** LOW
+**Difficulty:** 4/10 (medium)
+**Effort:** 3-4 hours
+**Value:** Marginal improvement in parsing reliability
+
+---
+
+### 4. Parallel Codebase Mapping (Brownfield Analysis)
+
+#### Problem Statement
+**Current behavior in Lynkr:**
+- Explore agent exists but sequential
+- No structured codebase documentation
+- Ad-hoc analysis per user request
+
+**GSD's solution:**
+- `/gsd:map-codebase` spawns 7 parallel agents
+- Generates structured documents:
+  - STACK.md (tech stack)
+  - ARCHITECTURE.md (system design)
+  - CONVENTIONS.md (code style)
+  - CONCERNS.md (tech debt)
+  - API.md (external interfaces)
+  - DATA.md (data models)
+  - FLOWS.md (user journeys)
+
+#### Implementation Plan
+
+**Files to create:**
+- `src/agents/codebase-mapper.js` - Orchestrates parallel analysis
+- `src/agents/analyzers/stack-analyzer.js` - Tech stack detection
+- `src/agents/analyzers/architecture-analyzer.js` - System design
+- `src/agents/analyzers/conventions-analyzer.js` - Code style
+- `src/agents/analyzers/concerns-analyzer.js` - Tech debt
+- `src/agents/analyzers/api-analyzer.js` - External APIs
+- `src/agents/analyzers/data-analyzer.js` - Data models
+- `src/agents/analyzers/flows-analyzer.js` - User flows
+
+**Code implementation:**
+```javascript
+// src/agents/codebase-mapper.js (NEW FILE)
+
+const logger = require("../logger");
+const { executeAgent } = require("./index");
+const fs = require("fs/promises");
+const path = require("path");
+
+/**
+ * Map existing codebase by spawning parallel analysis agents
+ */
+async function mapCodebase(options = {}) {
+  const {
+    workspaceRoot = process.cwd(),
+    outputDir = path.join(workspaceRoot, ".lynkr", "codebase-map")
+  } = options;
+
+  logger.info({ workspaceRoot, outputDir }, "Starting parallel codebase analysis");
+
+  // Ensure output directory exists
+  await fs.mkdir(outputDir, { recursive: true });
+
+  // Spawn 7 parallel analysis agents
+  const analyses = [
+    { name: "stack", file: "STACK.md", prompt: "Analyze tech stack and dependencies" },
+    { name: "architecture", file: "ARCHITECTURE.md", prompt: "Document system architecture and design patterns" },
+    { name: "conventions", file: "CONVENTIONS.md", prompt: "Extract code conventions and style guides" },
+    { name: "concerns", file: "CONCERNS.md", prompt: "Identify tech debt and areas of concern" },
+    { name: "api", file: "API.md", prompt: "Document external APIs and integrations" },
+    { name: "data", file: "DATA.md", prompt: "Map data models and schemas" },
+    { name: "flows", file: "FLOWS.md", prompt: "Trace key user flows and business logic" }
+  ];
+
+  // Run all analyses in parallel
+  const results = await Promise.all(
+    analyses.map(analysis =>
+      runAnalysisAgent(analysis, workspaceRoot, outputDir)
+    )
+  );
+
+  // Generate summary document
+  await generateSummary(results, outputDir);
+
+  logger.info({
+    outputDir,
+    documents: results.length
+  }, "Codebase analysis complete");
+
+  return {
+    outputDir,
+    documents: results.map(r => r.file)
+  };
+}
+
+async function runAnalysisAgent(analysis, workspaceRoot, outputDir) {
+  const { name, file, prompt } = analysis;
+
+  logger.info({ name, file }, `Starting ${name} analysis`);
+
+  const result = await executeAgent({
+    agentType: "explore",
+    task: `${prompt}
+
+    Analyze the codebase at ${workspaceRoot} and generate a comprehensive ${file} document.
+
+    Guidelines:
+    - Be thorough but concise
+    - Use markdown formatting
+    - Include code examples where relevant
+    - Highlight important patterns and conventions
+    - Note any concerns or recommendations
+
+    Output the complete document content.`,
+    workspaceRoot,
+    maxSteps: 10,
+    model: "sonnet" // Use sonnet for quality analysis
+  });
+
+  // Write result to file
+  const filePath = path.join(outputDir, file);
+  await fs.writeFile(filePath, result.output, "utf8");
+
+  logger.info({ name, file, filePath }, `Completed ${name} analysis`);
+
+  return {
+    name,
+    file,
+    filePath,
+    content: result.output
+  };
+}
+
+async function generateSummary(results, outputDir) {
+  const summary = `# Codebase Analysis Summary
+
+Generated: ${new Date().toISOString()}
+
+## Documents Generated
+
+${results.map(r => `- [${r.name.toUpperCase()}](${r.file}) - ${r.content.split('\n')[0].replace(/^#\s*/, '')}`).join('\n')}
+
+## Quick Start
+
+1. Read STACK.md to understand the technology choices
+2. Review ARCHITECTURE.md for system design
+3. Check CONVENTIONS.md before making changes
+4. Scan CONCERNS.md for known issues
+5. Reference API.md for external integrations
+6. Study DATA.md for data models
+7. Trace FLOWS.md for business logic
+
+---
+
+*Generated by Lynkr Codebase Mapper*
+`;
+
+  await fs.writeFile(
+    path.join(outputDir, "README.md"),
+    summary,
+    "utf8"
+  );
+}
+
+module.exports = {
+  mapCodebase
+};
+```
+
+**API endpoint:**
+```javascript
+// src/api/router.js
+
+router.post("/v1/codebase/map", rateLimiter, async (req, res, next) => {
+  try {
+    const { workspaceRoot, outputDir } = req.body;
+
+    const { mapCodebase } = require("../agents/codebase-mapper");
+    const result = await mapCodebase({
+      workspaceRoot: workspaceRoot || process.cwd(),
+      outputDir
+    });
+
+    res.json({
+      success: true,
+      outputDir: result.outputDir,
+      documents: result.documents,
+      message: `Generated ${result.documents.length} analysis documents`
+    });
+  } catch (error) {
+    next(error);
+  }
+});
+```
+
+**Priority:** MEDIUM
+**Difficulty:** 7/10 (high)
+**Effort:** 8-10 hours
+**Value:** Excellent for onboarding to large codebases
+
+---
+
+### 5. Automatic Git Commits Per Task
+
+#### Problem Statement
+**Current behavior in Lynkr:**
+- Git operations are manual
+- No automatic commits
+- No task-to-commit mapping
+- Hard to bisect or rollback atomic changes
+
+**GSD's solution:**
+- Automatic commit after each task completion
+- Commit message includes task context
+- Enables git bisect for debugging
+- Clear audit trail
+
+#### Implementation Plan
+
+**Files to modify:**
+- `src/utils/git-integration.js` - New file for git operations
+- `src/orchestrator/index.js` - Hook into task completion
+- `src/config/index.js` - Add git config
+
+**Configuration:**
+```javascript
+// .env
+GIT_AUTO_COMMIT=false              # Enable automatic commits per task
+GIT_AUTO_COMMIT_MESSAGE_PREFIX=🤖   # Prefix for auto-commits
+GIT_COMMIT_AFTER_TASK=true         # Commit after each TodoWrite completion
+GIT_INCLUDE_TASK_CONTEXT=true     # Include task details in commit message
+```
+
+**Code implementation:**
+```javascript
+// src/utils/git-integration.js (NEW FILE)
+
+const { execSync } = require("child_process");
+const logger = require("../logger");
+const config = require("../config");
+
+/**
+ * Create automatic commit after task completion
+ */
+async function autoCommitTask(task, files = []) {
+  if (!config.GIT_AUTO_COMMIT) {
+    return { skipped: true, reason: "Auto-commit disabled" };
+  }
+
+  try {
+    // Check if we're in a git repo
+    const isGitRepo = await isGitRepository();
+    if (!isGitRepo) {
+      logger.warn("Not a git repository, skipping auto-commit");
+      return { skipped: true, reason: "Not a git repository" };
+    }
+
+    // Stage files
+    if (files.length > 0) {
+      for (const file of files) {
+        execSync(`git add "${file}"`, { encoding: "utf8" });
+      }
+    } else {
+      // Stage all changes
+      execSync("git add -A", { encoding: "utf8" });
+    }
+
+    // Check if there are changes to commit
+    const status = execSync("git status --porcelain", { encoding: "utf8" });
+    if (!status.trim()) {
+      logger.info("No changes to commit");
+      return { skipped: true, reason: "No changes" };
+    }
+
+    // Generate commit message
+    const commitMessage = generateCommitMessage(task);
+
+    // Create commit
+    execSync(`git commit -m "${commitMessage}"`, { encoding: "utf8" });
+
+    logger.info({ task: task.content, files }, "Auto-committed task completion");
+
+    return {
+      success: true,
+      message: commitMessage,
+      files
+    };
+
+  } catch (error) {
+    logger.error({ error: error.message, task }, "Failed to auto-commit");
+    return {
+      skipped: true,
+      reason: "Commit failed",
+      error: error.message
+    };
+  }
+}
+
+function generateCommitMessage(task) {
+  const prefix = config.GIT_AUTO_COMMIT_MESSAGE_PREFIX || "🤖";
+  const taskName = task.content || "Task completed";
+
+  let message = `${prefix} ${taskName}`;
+
+  if (config.GIT_INCLUDE_TASK_CONTEXT && task.description) {
+    message += `\n\n${task.description}`;
+  }
+
+  message += "\n\n🤖 Generated with Lynkr";
+
+  if (task.verificationSteps) {
+    message += `\n\nVerification:\n${task.verificationSteps.map(s => `- ${s}`).join('\n')}`;
+  }
+
+  return message;
+}
+
+async function isGitRepository() {
+  try {
+    execSync("git rev-parse --git-dir", { encoding: "utf8", stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  autoCommitTask,
+  isGitRepository
+};
+```
+
+**Integration with TodoWrite:**
+```javascript
+// src/orchestrator/index.js
+
+const { autoCommitTask } = require("../utils/git-integration");
+
+// When marking task as completed
+async function handleTodoCompletion(task, session) {
+  // Extract files modified in this task
+  const modifiedFiles = extractModifiedFiles(session.messages, task);
+
+  // Auto-commit if enabled
+  if (config.GIT_COMMIT_AFTER_TASK) {
+    await autoCommitTask(task, modifiedFiles);
+  }
+}
+```
+
+**Priority:** LOW
+**Difficulty:** 3/10 (easy)
+**Effort:** 2-3 hours
+**Value:** Nice-to-have for audit trail
+
+---
+
+### 6. State Document Generation
+
+#### Problem Statement
+**Current behavior in Lynkr:**
+- Memory system stores unstructured memories
+- No explicit state tracking
+- Hard to understand "current position"
+- Resumption after interruption is manual
+
+**GSD's solution:**
+- STATE.md tracks current position, blockers, decisions
+- ROADMAP.md shows phases and progress
+- PROJECT.md captures goals and constraints
+
+#### Implementation Plan
+
+**Files to create:**
+- `src/utils/state-manager.js` - State document generation
+- `src/sessions/state-tracker.js` - Real-time state tracking
+
+**Configuration:**
+```javascript
+// .env
+STATE_TRACKING_ENABLED=true        # Generate STATE.md per session
+STATE_UPDATE_FREQUENCY=5           # Update state every N turns
+STATE_OUTPUT_DIR=.lynkr/state      # Where to store state documents
+```
+
+**Code implementation:**
+```javascript
+// src/utils/state-manager.js (NEW FILE)
+
+const fs = require("fs/promises");
+const path = require("path");
+const logger = require("../logger");
+
+/**
+ * Generate STATE.md document for session
+ */
+async function generateStateDocument(session, options = {}) {
+  const {
+    outputDir = path.join(process.cwd(), ".lynkr", "state"),
+    sessionId = session.id
+  } = options;
+
+  await fs.mkdir(outputDir, { recursive: true });
+
+  const state = extractSessionState(session);
+
+  const stateDocument = `# Session State
+
+**Session ID:** ${sessionId}
+**Last Updated:** ${new Date().toISOString()}
+**Provider:** ${session.provider || 'unknown'}
+**Total Tokens:** ${session.totalTokens || 0}
+
+---
+
+## Current Task
+
+${state.currentTask || '*No active task*'}
+
+### Progress
+${state.progress || '*Not tracked*'}
+
+---
+
+## Active Files
+
+${state.activeFiles.length > 0
+  ? state.activeFiles.map(f => `- ${f}`).join('\n')
+  : '*No files modified yet*'
+}
+
+---
+
+## Recent Decisions
+
+${state.decisions.length > 0
+  ? state.decisions.map((d, i) => `${i + 1}. ${d}`).join('\n')
+  : '*No major decisions recorded*'
+}
+
+---
+
+## Current Blockers
+
+${state.blockers.length > 0
+  ? state.blockers.map(b => `- ❌ ${b}`).join('\n')
+  : '*No blockers*'
+}
+
+---
+
+## Next Steps
+
+${state.nextSteps.length > 0
+  ? state.nextSteps.map((s, i) => `${i + 1}. ${s}`).join('\n')
+  : '*To be determined*'
+}
+
+---
+
+## Context Budget
+
+- **Used:** ${session.totalTokens || 0} tokens
+- **Warning Threshold:** ${session.warningThreshold || 150000} tokens
+- **Max Threshold:** ${session.maxThreshold || 180000} tokens
+- **Utilization:** ${Math.round((session.totalTokens || 0) / (session.maxThreshold || 180000) * 100)}%
+
+${session.totalTokens > (session.warningThreshold || 150000)
+  ? '\n⚠️ **Warning:** Approaching context limit. Consider breaking down remaining work.\n'
+  : ''
+}
+
+---
+
+*Generated by Lynkr State Tracker*
+`;
+
+  const filePath = path.join(outputDir, `STATE-${sessionId}.md`);
+  await fs.writeFile(filePath, stateDocument, "utf8");
+
+  logger.info({ sessionId, filePath }, "Updated state document");
+
+  return { filePath, state };
+}
+
+function extractSessionState(session) {
+  // Extract structured state from session messages
+  return {
+    currentTask: extractCurrentTask(session.messages),
+    progress: extractProgress(session.messages),
+    activeFiles: extractActiveFiles(session.messages),
+    decisions: extractDecisions(session.messages),
+    blockers: extractBlockers(session.messages),
+    nextSteps: extractNextSteps(session.messages)
+  };
+}
+
+function extractCurrentTask(messages) {
+  // Look for most recent TodoWrite with in_progress status
+  // Or extract from last user message
+  const lastUserMessage = messages.filter(m => m.role === "user").pop();
+  return lastUserMessage?.content || "No active task";
+}
+
+function extractActiveFiles(messages) {
+  // Look for Read, Write, Edit tool calls
+  const fileOperations = messages.filter(m =>
+    m.tool_calls?.some(t => ["Read", "Write", "Edit"].includes(t.name))
+  );
+
+  const files = new Set();
+  fileOperations.forEach(op => {
+    op.tool_calls?.forEach(tc => {
+      if (tc.input?.file_path) {
+        files.add(tc.input.file_path);
+      }
+    });
+  });
+
+  return Array.from(files);
+}
+
+function extractDecisions(messages) {
+  // Look for key decision points in conversation
+  // Heuristic: messages containing "decided", "chose", "going with", etc.
+  const decisionKeywords = /\b(decided|chose|selected|going with|opting for)\b/i;
+
+  return messages
+    .filter(m => m.role === "assistant" && decisionKeywords.test(m.content))
+    .slice(-5) // Last 5 decisions
+    .map(m => {
+      const lines = m.content.split('\n');
+      const decisionLine = lines.find(l => decisionKeywords.test(l));
+      return decisionLine?.trim() || m.content.substring(0, 100);
+    });
+}
+
+function extractBlockers(messages) {
+  // Look for mentions of blockers, errors, issues
+  const blockerKeywords = /\b(blocked|error|failed|issue|problem|cannot|unable)\b/i;
+
+  return messages
+    .filter(m => blockerKeywords.test(m.content))
+    .slice(-3) // Last 3 blockers
+    .map(m => {
+      const lines = m.content.split('\n');
+      const blockerLine = lines.find(l => blockerKeywords.test(l));
+      return blockerLine?.trim() || m.content.substring(0, 100);
+    });
+}
+
+function extractNextSteps(messages) {
+  // Look for mentions of "next", "then", "after", "should"
+  const nextStepKeywords = /\b(next|then|after that|should|will|going to)\b/i;
+
+  const lastFewMessages = messages.slice(-5);
+  return lastFewMessages
+    .filter(m => m.role === "assistant" && nextStepKeywords.test(m.content))
+    .flatMap(m => {
+      const lines = m.content.split('\n');
+      return lines
+        .filter(l => nextStepKeywords.test(l))
+        .map(l => l.trim());
+    })
+    .slice(0, 5); // Max 5 next steps
+}
+
+module.exports = {
+  generateStateDocument,
+  extractSessionState
+};
+```
+
+**Priority:** LOW
+**Difficulty:** 4/10 (medium)
+**Effort:** 3-4 hours
+**Value:** Helpful for long-running projects
+
+---
+
+## Implementation Priority Matrix
+
+| Feature | Priority | Difficulty | Effort | Value | Status |
+|---------|----------|-----------|--------|-------|--------|
+| Context Budget Warnings | **HIGH** | 5/10 | 4-6h | HIGH | 🔴 Missing |
+| Fresh Context per Task | **HIGH** | 5/10 | 4-6h | HIGH | 🔴 Missing |
+| Atomic Task Planning | **MEDIUM** | 6/10 | 6-8h | MEDIUM | 🔴 Missing |
+| Parallel Codebase Mapping | **MEDIUM** | 7/10 | 8-10h | MEDIUM | 🔴 Missing |
+| XML-Structured Prompts | **LOW** | 4/10 | 3-4h | LOW | 🔴 Missing |
+| Auto Git Commits | **LOW** | 3/10 | 2-3h | LOW | 🔴 Missing |
+| State Documents | **LOW** | 4/10 | 3-4h | LOW | 🔴 Missing |
+
+**Total Effort:** 30-41 hours (~1 week of focused work)
+
+---
+
+## Quick Win: Context Budget Warning (2 hours)
+
+The highest-value, lowest-effort feature to implement first:
+
+**Goal:** Warn when approaching context limits and suggest actions
+
+**Implementation:**
+```javascript
+// src/orchestrator/index.js (add after token estimation)
+
+function injectContextWarning(systemPrompt, estimatedTokens, maxTokens) {
+  const warningThreshold = maxTokens * 0.75; // 75% threshold
+
+  if (estimatedTokens > warningThreshold) {
+    const utilization = Math.round(estimatedTokens / maxTokens * 100);
+
+    systemPrompt += `\n\n<context-budget-warning>
+⚠️ CONTEXT BUDGET ALERT ⚠️
+
+Current usage: ${estimatedTokens}/${maxTokens} tokens (${utilization}%)
+
+You are approaching the context limit. Quality may degrade soon.
+
+RECOMMENDED ACTIONS:
+1. Complete current task before starting new work
+2. Suggest breaking remaining work into smaller subtasks
+3. Offer to summarize completed work and start fresh session
+
+DO NOT:
+- Start new complex tasks
+- Add unnecessary detail
+- Expand scope beyond current task
+</context-budget-warning>`;
+  }
+
+  return systemPrompt;
+}
+```
+
+---
+
+## Comparison: What Lynkr Already Has
+
+| Feature | Lynkr | GSD | Notes |
+|---------|-------|-----|-------|
+| **Multi-provider** | ✅ 9 providers | ❌ Claude only | Major advantage |
+| **Token optimization** | ✅ 60-80% savings | ❌ Not mentioned | Caching + tool selection |
+| **Memory system** | ✅ Titans-inspired | ✅ STATE.md | Different approaches |
+| **Tool execution** | ✅ Server + passthrough | ✅ Passthrough | More flexible |
+| **IDE integration** | ✅ Cursor/OpenAI API | ❌ CLI only | Better UX |
+| **Hybrid routing** | ✅ Local + cloud | ❌ No routing | Cost optimization |
+| **Streaming** | ✅ SSE support | ❌ Not mentioned | Real-time feedback |
+| **Rate limiting** | ✅ Configurable | ❌ Not mentioned | Production-ready |
+| **Session management** | ✅ SQLite + memory | ✅ File-based | More robust |
+| **Agent system** | ✅ Multiple types | ✅ Task agents | Similar capability |
+
+---
+
+## Recommendations
+
+### Phase 1: Quick Wins (Week 1)
+1. ✅ **Context budget warnings** (2 hours) - HIGHEST VALUE
+2. ✅ **Auto git commits** (3 hours) - Nice audit trail
+3. ✅ **State document generation** (4 hours) - Better resumption
+
+**Total:** 9 hours
+
+### Phase 2: Core Features (Week 2)
+4. ✅ **Fresh context spawning** (6 hours) - Prevents degradation
+5. ✅ **Atomic task planning** (8 hours) - Better success rate
+
+**Total:** 14 hours
+
+### Phase 3: Advanced Features (Week 3)
+6. ✅ **Parallel codebase mapping** (10 hours) - Brownfield onboarding
+7. ⚠️ **XML prompts** (4 hours) - Optional, low value
+
+**Total:** 14 hours
+
+---
+
+## Conclusion
+
+GSD has excellent patterns for **context management** and **task breakdown** that would complement Lynkr's strengths in **multi-provider support** and **token optimization**.
+
+**Recommended approach:**
+1. Start with **context budget warnings** (2 hours, high value)
+2. Add **fresh context spawning** (6 hours, prevents quality loss)
+3. Implement **atomic task planning** (8 hours, improves reliability)
+4. Consider **codebase mapping** for brownfield projects (10 hours)
+
+**Total minimum viable enhancement:** 16 hours for top 3 features
+
+This would give Lynkr the best of both worlds:
+- ✅ GSD's context management + task breakdown
+- ✅ Lynkr's multi-provider + token optimization + IDE integration
+
+---
+
+**Next Steps:**
+1. Review this document
+2. Prioritize features based on user needs
+3. Start with context budget warnings (quick win)
+4. Iterate based on feedback