begin-session

name	begin-session
description	Start development session with diagnostics, context loading, and intelligent task menu Use when this capability is needed.
metadata	{"author":"eyeinthesky6"}

BEGIN SESSION - Development Session Entry Point

Purpose: Single command to start any development session with full context and intelligent recommendations.

What This Workflow Does

1. Loads Context (60s)

   • Read today's AI tracking documents
   • Check sprint status
   • Review recent git commits
   • Find unfinished work

2. Runs Diagnostics (2min)

   • Lint errors (via framework adapter)
   • Type errors (via framework adapter)
   • TODO/FIXME/HACK count (via framework adapter)
   • Circular dependencies (via framework adapter)
   • Build status (via framework adapter)

3. Analyzes State (30s)

   • Identify problem areas
   • Find incomplete features
   • Check for security issues

4. Presents Task Menu

   • Data-driven task recommendations
   • Clear options with priorities
   • Contextual suggestions

5. Routes to Workflow

   • Based on user choice
   • Passes diagnostic context to next workflow

---

Input Schema

{
  "projectRoot": "path/to/project",
  "trackingDocs": ["docs/AITracking/**", "docs/SprintStatus/**"],
  "userPreferences": {
    "showGitLog": true,
    "showDiagnostics": true,
    "autoRecommend": true
  }
}

---

Output Schema

{
  "diagnostics": {
    "lintErrors": 0,
    "typeErrors": 0,
    "todoCount": 0,
    "circularDeps": 0,
    "buildStatus": "pass|fail"
  },
  "context": {
    "todaysWork": ["list of files"],
    "recentCommits": ["commit messages"],
    "unfinishedWork": ["incomplete items"]
  },
  "recommendations": [
    {
      "task": "implement-feature",
      "priority": "high"
       
    
  
   
     ...
     ...
     ...
     ...
  

---

Execution Steps (Framework-Agnostic)

Step 1: Load Context

Read tracking documents:

// Get today's date
const today = new Date().toLocaleDateString('en-GB').replace(/\//g, '-'); // DD-MM-YYYY

// Read AI tracking
const trackingFiles = await glob(`docs/AITracking/AIAction_${today}_*.md`);
const todaysWork = await Promise.all(trackingFiles.map(f => readFile(f)));

// Read sprint status
const sprintStatus = await readFile(`docs/SprintStatus/Sprint Status-${today}.md`);

// Get recent git commits
const recentCommits = await git.log({ since: '8 hours ago', maxCount: 10 });

// Find unfinished work
const auditFiles = await glob(`docs/audit/**/*${today}*`);

Step 2: Run Diagnostics (Using Framework Adapter)

Detect project type and run appropriate commands:

// Detect framework adapter
const adapter = await adapterRegistry.detect(projectRoot);
if (!adapter) {
  throw new Error('No framework adapter detected');
}

// Run diagnostics via adapter
const lintResult = await adapter.lint();
const typeCheckResult = await adapter.typeCheck();
const buildResult = await adapter.build();

// Find TODOs via adapter
const todos = await adapter.findTodos();

// Find circular dependencies (if supported)
const circularDeps = adapter.findCircularDeps 
  ? await adapter.findCircularDeps()
  : [];

// Compile diagnostics
const diagnostics = {
  lintErrors: countErrors(lintResult.stderr),
  typeErrors: countErrors(typeCheckResult.stderr),
  todoCount: todos.length,
  circularDeps: circularDeps.length,
  buildStatus: buildResult.success ? 'pass' : 'fail'
};

Step 3: Analyze State

Identify problem areas:

// Parse errors to find problem files
const problemAreas = analyzeDiagnostics(diagnostics);

// Find incomplete features (files with TODO/INCOMPLETE)
const incompleteFeatures = todos.filter(t => 
  t.includes('TODO') || t.includes('INCOMPLETE') || t.includes('FIXME')
);

// Check for high-priority security issues (if auditing available)
const securityIssues = await checkSecurityIssues();

Step 4: Present Task Menu

Generate menu based on diagnostics:

const menu = {
  development: [
    {
      id: 1,
      name: 'Implement Feature',
      workflow: 'implement-feature',
      condition: diagnostics.lintErrors < 50,
      description: 'Start new feature or resume incomplete feature'
    },
    {
      id: 2,
      name: 'Resume Work',
      workflow: 'continue',
      condition: unfinishedWork.length > 0,
      description: 'Continue from where you left off'
    }
  ],
  fixing: [
    {
      id: 3,
      name: 'Fix Errors',
      workflow: 'fix-all',
      condition: diagnostics.lintErrors > 0 || diagnostics.typeErrors > 0,
      priority: diagnostics.lintErrors > 50 ? 'critical' : 'medium',
      description: `Fix ${diagnostics.lintErrors} lint + ${diagnostics.typeErrors} type errors`
    },
    {
      id: 4,
      name: 'Complete Features',
      workflow: 'feature-fix-strategy',
      : diagnostics. > ,
      : 
    },
    {
      : ,
      : ,
      : ,
      : diagnostics. > ,
      : 
    }
  ],
  : [
    {
      : ,
      : ,
      : ,
      : ,
      : 
    },
    {
      : ,
      : ,
      : ,
      : ,
      : 
    },
    {
      : ,
      : ,
      : ,
      : ,
      : 
    },
    {
      : ,
      : ,
      : ,
      : ,
      : 
    }
  ],
  : [
    {
      : ,
      : ,
      : ,
      : ,
      : 
    },
    {
      : ,
      : ,
      : ,
      : ,
      : 
    }
  ]
};

Step 5: Make Recommendations

Data-driven suggestions:

const recommendations = [];

if (diagnostics.lintErrors > 100) {
  recommendations.push({
    task: 'fix-all',
    priority: 'critical',
    reason: `${diagnostics.lintErrors} lint errors - Must fix before continuing`
  });
} else if (diagnostics.lintErrors > 50) {
  recommendations.push({
    task: 'fix-all',
    priority: 'high',
    reason: `${diagnostics.lintErrors} lint errors - Should fix soon`
  });
} else if (diagnostics.typeErrors > 50) {
  recommendations.push({
    task: 'fix-all',
    priority: 'medium',
    reason: `${diagnostics.typeErrors} type errors need attention`
  });
} else if (diagnostics.todoCount > 100) {
  recommendations.push({
    task: 'todo-execution',
    priority: 'medium',
    reason: `${diagnostics.todoCount} TODOs need resolution`
  });
} else if (diagnostics. === ) {
  recommendations.({
    : ,
    : ,
    : 
  });
}  {
  recommendations.({
    : ,
    : ,
    : 
  });
}

 {
  diagnostics,
  context,
  menu,
  recommendations
};

---

Usage

From CLI:

# Run begin-session workflow
tsk run begin-session

# With specific project root
tsk run begin-session --input '{"projectRoot": "./my-project"}'

# Dry run (see what it would check)
tsk run begin-session --dry-run

From Code:

import { adapterRegistry, TypeScriptAdapter } from '@trinity-os/skillkit';

// Register adapter
const adapter = new TypeScriptAdapter(process.cwd());
adapterRegistry.register(adapter);

// Run workflow
const result = await runner.run('begin-session', {
  projectRoot: process.cwd(),
  trackingDocs: ['docs/AITracking/**', 'docs/SprintStatus/**'],
  userPreferences: {
    showGitLog: true,
    showDiagnostics: true,
    autoRecommend: true
  }
});

console.log(result.output.recommendations);

---

Success Criteria

Performance:

• ✅ Context loading: < 60 seconds
• ✅ Diagnostics: < 2 minutes
• ✅ Total execution: < 5 minutes

Output Quality:

• ✅ Clear diagnostic summary
• ✅ Data-driven recommendations
• ✅ Actionable task menu
• ✅ Contextual priority suggestions

User Experience:

• ✅ Understand codebase state immediately
• ✅ Know what needs attention
• ✅ Choose task based on data
• ✅ Start work within 5 minutes

---

Framework Compatibility

This workflow uses the framework adapter system and works with:

• ✅ TypeScript/JavaScript (npm, pnpm, yarn)
• ✅ Python (pip, poetry, pipenv)
• ✅ Java (maven, gradle)
• ✅ Go (go modules)
• ✅ PHP (composer)
• ✅ Ruby (bundler)
• ✅ C# (dotnet)

Adapter auto-detection ensures the right commands run for your project!

---

Related Workflows

• implement-feature - Start new feature development
• continue - Resume previous work
• fix-all - Systematic error fixing
• final-check - Pre-deployment quality gate
• system-audit - Full codebase review

---

Status: ✅ Production Ready
Type: Workflow (Orchestrator)
Execution Mode: Hybrid (Native diagnostics + Instructional menu)
Last Updated: November 5, 2025

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.