jettypod 3.0.1

package/lib/bug-workflow.js

@@ -0,0 +1,94 @@
+/**
+ * Bug workflow guidance constants
+ * Shared between CLAUDE.md generation and terminal display
+ */
+
+const BUG_WORKFLOW_STEPS = `1. REPRODUCE
+   □ Create minimal reproduction case
+   □ Write down exact steps to trigger
+   □ Note what you expect vs what happens
+   □ Check if issue exists in latest code
+
+2. INVESTIGATE
+   □ Read error messages/stack traces completely
+   □ Check relevant code around the issue
+   □ Look for recent changes (git log/blame)
+   □ Search for similar bugs (closed issues)
+
+3. ISOLATE
+   □ Narrow down to specific file/function
+   □ Identify root cause, not just symptoms
+   □ Verify your hypothesis with logging/debugging
+   □ Understand why the bug occurs
+
+4. FIX
+   □ Make the minimal change that fixes root cause
+   □ Avoid "while I'm here" refactoring
+   □ Add defensive checks if appropriate
+   □ Update error messages to be clearer
+
+5. VERIFY
+   □ Confirm original reproduction case now works
+   □ Run existing tests - ensure nothing broke
+   □ Add regression test for this specific bug
+   □ Test edge cases around the fix
+
+6. COMMIT
+   □ Clear commit message: "fix: [brief description]"
+   □ Reference issue number if applicable
+   □ Explain what caused it and how you fixed it
+   □ Push and verify CI passes`;
+
+const BUG_WORKFLOW_TECHNIQUES = `DEBUGGING TECHNIQUES:
+• Add strategic console.log/print statements
+• Use git bisect to find when bug was introduced
+• Compare working vs broken behavior side-by-side
+• Rubber duck: explain the bug out loud
+• Take breaks - fresh eyes spot issues faster`;
+
+const BUG_WORKFLOW_RED_FLAGS = `RED FLAGS:
+❌ "It works on my machine" - not fixed
+❌ Fixing symptoms without understanding cause
+❌ Adding try/catch to hide errors
+❌ Skipping reproduction - you'll miss edge cases`;
+
+/**
+ * Get bug workflow for CLAUDE.md (plain text format)
+ * @returns {string} Formatted workflow for markdown
+ */
+function getBugWorkflowForClaudeMd() {
+  return `SYSTEMATIC BUG FIXING WORKFLOW:
+
+${BUG_WORKFLOW_STEPS}
+
+${BUG_WORKFLOW_TECHNIQUES}
+
+${BUG_WORKFLOW_RED_FLAGS}`;
+}
+
+/**
+ * Get bug workflow for terminal display (with formatting/colors)
+ * @returns {string} Formatted workflow for terminal
+ */
+function getBugWorkflowForTerminal() {
+  return `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🐛  BUG FIXING WORKFLOW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+${BUG_WORKFLOW_STEPS}
+
+${BUG_WORKFLOW_TECHNIQUES}
+
+${BUG_WORKFLOW_RED_FLAGS}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+}
+
+module.exports = {
+  BUG_WORKFLOW_STEPS,
+  BUG_WORKFLOW_TECHNIQUES,
+  BUG_WORKFLOW_RED_FLAGS,
+  getBugWorkflowForClaudeMd,
+  getBugWorkflowForTerminal
+};

package/lib/bug-workflow.test.js

@@ -0,0 +1,177 @@
+const {
+  BUG_WORKFLOW_STEPS,
+  BUG_WORKFLOW_TECHNIQUES,
+  BUG_WORKFLOW_RED_FLAGS,
+  getBugWorkflowForClaudeMd,
+  getBugWorkflowForTerminal
+} = require('./bug-workflow');
+
+describe('Bug Workflow Module', () => {
+  describe('Constants', () => {
+    test('BUG_WORKFLOW_STEPS contains all 6 steps', () => {
+      expect(BUG_WORKFLOW_STEPS).toContain('1. REPRODUCE');
+      expect(BUG_WORKFLOW_STEPS).toContain('2. INVESTIGATE');
+      expect(BUG_WORKFLOW_STEPS).toContain('3. ISOLATE');
+      expect(BUG_WORKFLOW_STEPS).toContain('4. FIX');
+      expect(BUG_WORKFLOW_STEPS).toContain('5. VERIFY');
+      expect(BUG_WORKFLOW_STEPS).toContain('6. COMMIT');
+    });
+
+    test('BUG_WORKFLOW_STEPS contains critical checklist items', () => {
+      // REPRODUCE checklist
+      expect(BUG_WORKFLOW_STEPS).toContain('Create minimal reproduction case');
+      expect(BUG_WORKFLOW_STEPS).toContain('Write down exact steps to trigger');
+
+      // INVESTIGATE checklist
+      expect(BUG_WORKFLOW_STEPS).toContain('Read error messages/stack traces completely');
+      expect(BUG_WORKFLOW_STEPS).toContain('Look for recent changes (git log/blame)');
+
+      // ISOLATE checklist
+      expect(BUG_WORKFLOW_STEPS).toContain('Identify root cause, not just symptoms');
+      expect(BUG_WORKFLOW_STEPS).toContain('Understand why the bug occurs');
+
+      // FIX checklist
+      expect(BUG_WORKFLOW_STEPS).toContain('Make the minimal change that fixes root cause');
+      expect(BUG_WORKFLOW_STEPS).toContain('Avoid "while I\'m here" refactoring');
+
+      // VERIFY checklist
+      expect(BUG_WORKFLOW_STEPS).toContain('Add regression test for this specific bug');
+      expect(BUG_WORKFLOW_STEPS).toContain('Run existing tests - ensure nothing broke');
+
+      // COMMIT checklist
+      expect(BUG_WORKFLOW_STEPS).toContain('Clear commit message: "fix: [brief description]"');
+      expect(BUG_WORKFLOW_STEPS).toContain('Reference issue number if applicable');
+    });
+
+    test('BUG_WORKFLOW_TECHNIQUES contains debugging tips', () => {
+      expect(BUG_WORKFLOW_TECHNIQUES).toContain('DEBUGGING TECHNIQUES:');
+      expect(BUG_WORKFLOW_TECHNIQUES).toContain('git bisect');
+      expect(BUG_WORKFLOW_TECHNIQUES).toContain('Rubber duck');
+      expect(BUG_WORKFLOW_TECHNIQUES).toContain('Take breaks');
+    });
+
+    test('BUG_WORKFLOW_RED_FLAGS contains anti-patterns', () => {
+      expect(BUG_WORKFLOW_RED_FLAGS).toContain('RED FLAGS:');
+      expect(BUG_WORKFLOW_RED_FLAGS).toContain('"It works on my machine"');
+      expect(BUG_WORKFLOW_RED_FLAGS).toContain('Fixing symptoms without understanding cause');
+      expect(BUG_WORKFLOW_RED_FLAGS).toContain('Adding try/catch to hide errors');
+      expect(BUG_WORKFLOW_RED_FLAGS).toContain('Skipping reproduction');
+    });
+  });
+
+  describe('getBugWorkflowForClaudeMd()', () => {
+    test('returns string with all workflow sections', () => {
+      const result = getBugWorkflowForClaudeMd();
+
+      expect(typeof result).toBe('string');
+      expect(result).toContain('SYSTEMATIC BUG FIXING WORKFLOW:');
+      expect(result).toContain(BUG_WORKFLOW_STEPS);
+      expect(result).toContain(BUG_WORKFLOW_TECHNIQUES);
+      expect(result).toContain(BUG_WORKFLOW_RED_FLAGS);
+    });
+
+    test('does not contain terminal formatting characters', () => {
+      const result = getBugWorkflowForClaudeMd();
+
+      // Should not have Unicode box-drawing characters
+      expect(result).not.toContain('━');
+      // Should not have emojis
+      expect(result).not.toContain('🐛');
+    });
+
+    test('has plain text header for markdown compatibility', () => {
+      const result = getBugWorkflowForClaudeMd();
+
+      expect(result).toContain('SYSTEMATIC BUG FIXING WORKFLOW:');
+    });
+  });
+
+  describe('getBugWorkflowForTerminal()', () => {
+    test('returns string with all workflow sections', () => {
+      const result = getBugWorkflowForTerminal();
+
+      expect(typeof result).toBe('string');
+      expect(result).toContain(BUG_WORKFLOW_STEPS);
+      expect(result).toContain(BUG_WORKFLOW_TECHNIQUES);
+      expect(result).toContain(BUG_WORKFLOW_RED_FLAGS);
+    });
+
+    test('contains terminal formatting characters', () => {
+      const result = getBugWorkflowForTerminal();
+
+      // Should have Unicode box-drawing characters for borders
+      expect(result).toContain('━');
+      // Should have bug emoji
+      expect(result).toContain('🐛');
+    });
+
+    test('has formatted header with emoji', () => {
+      const result = getBugWorkflowForTerminal();
+
+      expect(result).toContain('🐛  BUG FIXING WORKFLOW');
+    });
+
+    test('has top and bottom borders', () => {
+      const result = getBugWorkflowForTerminal();
+
+      // Count border lines
+      const borderCount = (result.match(/━━━━━━━/g) || []).length;
+      expect(borderCount).toBeGreaterThanOrEqual(2); // Top and bottom borders
+    });
+  });
+
+  describe('Content Consistency', () => {
+    test('both formats contain the same workflow steps', () => {
+      const claudeMd = getBugWorkflowForClaudeMd();
+      const terminal = getBugWorkflowForTerminal();
+
+      // Both should contain the exact same steps content
+      expect(claudeMd).toContain(BUG_WORKFLOW_STEPS);
+      expect(terminal).toContain(BUG_WORKFLOW_STEPS);
+    });
+
+    test('both formats contain the same techniques', () => {
+      const claudeMd = getBugWorkflowForClaudeMd();
+      const terminal = getBugWorkflowForTerminal();
+
+      expect(claudeMd).toContain(BUG_WORKFLOW_TECHNIQUES);
+      expect(terminal).toContain(BUG_WORKFLOW_TECHNIQUES);
+    });
+
+    test('both formats contain the same red flags', () => {
+      const claudeMd = getBugWorkflowForClaudeMd();
+      const terminal = getBugWorkflowForTerminal();
+
+      expect(claudeMd).toContain(BUG_WORKFLOW_RED_FLAGS);
+      expect(terminal).toContain(BUG_WORKFLOW_RED_FLAGS);
+    });
+  });
+
+  describe('Edge Cases', () => {
+    test('functions return non-empty strings', () => {
+      expect(getBugWorkflowForClaudeMd().length).toBeGreaterThan(0);
+      expect(getBugWorkflowForTerminal().length).toBeGreaterThan(0);
+    });
+
+    test('functions are deterministic (same output on multiple calls)', () => {
+      const claudeMd1 = getBugWorkflowForClaudeMd();
+      const claudeMd2 = getBugWorkflowForClaudeMd();
+      expect(claudeMd1).toBe(claudeMd2);
+
+      const terminal1 = getBugWorkflowForTerminal();
+      const terminal2 = getBugWorkflowForTerminal();
+      expect(terminal1).toBe(terminal2);
+    });
+
+    test('constants are immutable strings', () => {
+      expect(typeof BUG_WORKFLOW_STEPS).toBe('string');
+      expect(typeof BUG_WORKFLOW_TECHNIQUES).toBe('string');
+      expect(typeof BUG_WORKFLOW_RED_FLAGS).toBe('string');
+
+      // Verify they're not empty
+      expect(BUG_WORKFLOW_STEPS.length).toBeGreaterThan(0);
+      expect(BUG_WORKFLOW_TECHNIQUES.length).toBeGreaterThan(0);
+      expect(BUG_WORKFLOW_RED_FLAGS.length).toBeGreaterThan(0);
+    });
+  });
+});

package/lib/claudemd.js

@@ -0,0 +1,130 @@
+const fs = require('fs');
+const path = require('path');
+const config = require('./config');
+const { getBugWorkflowForClaudeMd } = require('./bug-workflow');
+
+/**
+ * Get absolute path to CLAUDE.md file
+ * @returns {string} Absolute path to CLAUDE.md
+ */
+function getClaudeMdPath() {
+  return path.join(process.cwd(), 'CLAUDE.md');
+}
+
+/**
+ * Validate current work object structure
+ * @param {Object} currentWork - Current work item
+ * @throws {Error} If currentWork is invalid
+ */
+function validateCurrentWork(currentWork) {
+  if (!currentWork || typeof currentWork !== 'object') {
+    throw new Error('Current work must be an object');
+  }
+  if (!currentWork.id || typeof currentWork.id !== 'number') {
+    throw new Error('Current work must have a numeric id');
+  }
+  if (!currentWork.title || typeof currentWork.title !== 'string') {
+    throw new Error('Current work must have a string title');
+  }
+  if (!currentWork.type || typeof currentWork.type !== 'string') {
+    throw new Error('Current work must have a string type');
+  }
+  if (!currentWork.status || typeof currentWork.status !== 'string') {
+    throw new Error('Current work must have a string status');
+  }
+}
+
+// getModeBehaviorContent function removed - skills now provide all mode guidance
+// Mode-specific workflows are now handled by:
+// - speed-mode skill (activated on speed chore start)
+// - stable-mode skill (activated on stable chore start)
+// See .claude/skills/ directory for skill implementations
+
+/**
+ * Update current work section in CLAUDE.md
+ * @param {Object} currentWork - Current work item to display
+ * @param {string|null} mode - Work item mode (null for epics, undefined to read from config)
+ * @throws {Error} If currentWork is invalid or file cannot be written
+ */
+function updateCurrentWork(currentWork, mode) {
+  validateCurrentWork(currentWork);
+
+  const claudePath = getClaudeMdPath();
+
+  if (!fs.existsSync(claudePath)) {
+    return;
+  }
+
+  let content;
+  try {
+    content = fs.readFileSync(claudePath, 'utf-8');
+  } catch (err) {
+    throw new Error(`Failed to read CLAUDE.md: ${err.message}`);
+  }
+
+  // Use provided mode
+  // null = epic (no mode), undefined = fallback to config for backwards compatibility
+  let currentMode = mode;
+  if (currentMode === undefined) {
+    try {
+      const cfg = config.read();
+      currentMode = cfg.mode || 'speed';
+    } catch (err) {
+      currentMode = 'speed';
+    }
+  }
+
+  // Build new current_work section
+  let newCurrentWork = `<current_work>
+Working on: [#${currentWork.id}] ${currentWork.title} (${currentWork.type})`;
+
+  if (currentWork.epic_title && currentWork.epic_id !== currentWork.id) {
+    newCurrentWork += `
+Epic: [#${currentWork.epic_id}] ${currentWork.epic_title}`;
+  }
+
+  // Only add Mode line if mode is not null (epics don't have modes)
+  if (currentMode !== null) {
+    newCurrentWork += `
+Mode: ${currentMode}`;
+  }
+
+  newCurrentWork += `
+Status: ${currentWork.status}
+</current_work>`;
+
+  // Replace existing current_work section or add after project context
+  if (content.includes('<current_work>')) {
+    content = content.replace(/<current_work>[\s\S]*?<\/current_work>/, newCurrentWork);
+  } else {
+    // Insert after <claude_context> opening
+    if (!content.includes('<claude_context')) {
+      throw new Error('CLAUDE.md does not contain <claude_context> tag');
+    }
+    content = content.replace(/(<claude_context[^>]*>)/, `$1\n\n${newCurrentWork}`);
+  }
+
+  // Remove both <bug_workflow> and <mode_behavior> sections
+  // Skills now provide all mode-specific guidance via activation messages
+  content = content.replace(/<bug_workflow>[\s\S]*?<\/bug_workflow>/, '');
+  content = content.replace(/<mode_behavior>[\s\S]*?<\/mode_behavior>/, '');
+
+  // Update <mode> tag
+  if (currentMode !== null) {
+    content = content.replace(/<mode>.*?<\/mode>/, `<mode>${currentMode}</mode>`);
+  } else {
+    // Remove <mode> tag for epics
+    content = content.replace(/<mode>.*?<\/mode>\n?/, '');
+  }
+
+  try {
+    fs.writeFileSync(claudePath, content);
+  } catch (err) {
+    throw new Error(`Failed to write CLAUDE.md: ${err.message}`);
+  }
+}
+
+module.exports = {
+  updateCurrentWork,
+  getClaudeMdPath
+};

package/lib/claudemd.test.js

@@ -0,0 +1,195 @@
+const fs = require('fs');
+const path = require('path');
+const { createTestEnvironment } = require('./test-helpers');
+const { updateCurrentWork, getClaudeMdPath } = require('./claudemd');
+const config = require('./config');
+
+describe('CLAUDE.md Updater Module', () => {
+  let testEnv;
+
+  beforeEach(() => {
+    testEnv = createTestEnvironment();
+    process.chdir(testEnv.testDir);
+
+    // Initialize config
+    const jettypodDir = path.join(testEnv.testDir, '.jettypod');
+    fs.mkdirSync(jettypodDir);
+    config.write({ mode: 'speed', stage: 'starting' });
+  });
+
+  afterEach(() => {
+    testEnv.cleanup();
+  });
+
+  const validWorkItem = {
+    id: 1,
+    title: 'Test Feature',
+    type: 'feature',
+    status: 'in_progress',
+    epic_id: 10,
+    epic_title: 'Test Epic'
+  };
+
+  describe('getClaudeMdPath()', () => {
+    test('should return path to CLAUDE.md in current directory', () => {
+      const claudePath = getClaudeMdPath();
+      expect(claudePath).toContain('CLAUDE.md');
+      expect(claudePath).toBe(path.join(process.cwd(), 'CLAUDE.md'));
+    });
+  });
+
+  describe('updateCurrentWork()', () => {
+    const basicClaudeContent = `<claude_context project="test">
+<project_summary>Test project</project_summary>
+</claude_context>`;
+
+    test('should do nothing if CLAUDE.md does not exist', () => {
+      expect(() => updateCurrentWork(validWorkItem)).not.toThrow();
+    });
+
+    test('should add current_work section if it does not exist', () => {
+      fs.writeFileSync('CLAUDE.md', basicClaudeContent);
+
+      updateCurrentWork(validWorkItem);
+
+      const content = fs.readFileSync('CLAUDE.md', 'utf-8');
+      expect(content).toContain('<current_work>');
+      expect(content).toContain('Working on: [#1] Test Feature (feature)');
+      expect(content).toContain('Epic: [#10] Test Epic');
+      expect(content).toContain('Mode: speed');
+      expect(content).toContain('Status: in_progress');
+      expect(content).toContain('</current_work>');
+    });
+
+    test('should replace existing current_work section', () => {
+      const existingContent = `<claude_context project="test">
+<current_work>
+Working on: [#999] Old Feature (bug)
+Status: done
+</current_work>
+<project_summary>Test project</project_summary>
+</claude_context>`;
+
+      fs.writeFileSync('CLAUDE.md', existingContent);
+
+      updateCurrentWork(validWorkItem);
+
+      const content = fs.readFileSync('CLAUDE.md', 'utf-8');
+      expect(content).not.toContain('[#999] Old Feature');
+      expect(content).toContain('[#1] Test Feature');
+      expect(content).toContain('Status: in_progress');
+    });
+
+    test('should not include epic if work item is the epic itself', () => {
+      const epicWorkItem = {
+        id: 10,
+        title: 'Test Epic',
+        type: 'epic',
+        status: 'in_progress',
+        epic_id: 10,
+        epic_title: 'Test Epic'
+      };
+
+      fs.writeFileSync('CLAUDE.md', basicClaudeContent);
+
+      updateCurrentWork(epicWorkItem);
+
+      const content = fs.readFileSync('CLAUDE.md', 'utf-8');
+      expect(content).not.toContain('Epic: [#10]');
+      expect(content).toContain('[#10] Test Epic (epic)');
+    });
+
+    test('should not include epic if epic_title is missing', () => {
+      const workItemNoEpic = {
+        id: 1,
+        title: 'Test Feature',
+        type: 'feature',
+        status: 'in_progress'
+      };
+
+      fs.writeFileSync('CLAUDE.md', basicClaudeContent);
+
+      updateCurrentWork(workItemNoEpic);
+
+      const content = fs.readFileSync('CLAUDE.md', 'utf-8');
+      expect(content).not.toContain('Epic:');
+    });
+
+    test('should use mode from config', () => {
+      config.write({ mode: 'stable', stage: 'building' });
+      fs.writeFileSync('CLAUDE.md', basicClaudeContent);
+
+      updateCurrentWork(validWorkItem);
+
+      const content = fs.readFileSync('CLAUDE.md', 'utf-8');
+      expect(content).toContain('Mode: stable');
+    });
+
+    test('should use mode from config even if malformed', () => {
+      // Config module caches config, so we just verify it uses whatever mode is set
+      const currentConfig = config.read();
+      fs.writeFileSync('CLAUDE.md', basicClaudeContent);
+
+      updateCurrentWork(validWorkItem);
+
+      const content = fs.readFileSync('CLAUDE.md', 'utf-8');
+      expect(content).toContain(`Mode: ${currentConfig.mode || 'speed'}`);
+    });
+
+    test('should throw error for invalid work item - not an object', () => {
+      expect(() => updateCurrentWork(null)).toThrow('Current work must be an object');
+      expect(() => updateCurrentWork('string')).toThrow('Current work must be an object');
+    });
+
+    test('should throw error for missing id', () => {
+      const invalid = { ...validWorkItem, id: null };
+      expect(() => updateCurrentWork(invalid)).toThrow('Current work must have a numeric id');
+    });
+
+    test('should throw error for non-numeric id', () => {
+      const invalid = { ...validWorkItem, id: 'not-a-number' };
+      expect(() => updateCurrentWork(invalid)).toThrow('Current work must have a numeric id');
+    });
+
+    test('should throw error for missing title', () => {
+      const invalid = { ...validWorkItem, title: null };
+      expect(() => updateCurrentWork(invalid)).toThrow('Current work must have a string title');
+    });
+
+    test('should throw error for missing type', () => {
+      const invalid = { ...validWorkItem, type: null };
+      expect(() => updateCurrentWork(invalid)).toThrow('Current work must have a string type');
+    });
+
+    test('should throw error for missing status', () => {
+      const invalid = { ...validWorkItem, status: null };
+      expect(() => updateCurrentWork(invalid)).toThrow('Current work must have a string status');
+    });
+
+    test('should throw error if CLAUDE.md does not contain claude_context tag', () => {
+      fs.writeFileSync('CLAUDE.md', 'Just plain text, no tags');
+
+      expect(() => updateCurrentWork(validWorkItem)).toThrow('CLAUDE.md does not contain <claude_context> tag');
+    });
+
+    test('should preserve other sections in CLAUDE.md', () => {
+      const fullContent = `<claude_context project="test">
+<current_work>
+Working on: [#999] Old Feature (bug)
+</current_work>
+<project_summary>Test project</project_summary>
+<tech_stack>Node.js, Jest</tech_stack>
+<mode>speed</mode>
+</claude_context>`;
+
+      fs.writeFileSync('CLAUDE.md', fullContent);
+
+      updateCurrentWork(validWorkItem);
+
+      const content = fs.readFileSync('CLAUDE.md', 'utf-8');
+      expect(content).toContain('<project_summary>Test project</project_summary>');
+      expect(content).toContain('<tech_stack>Node.js, Jest</tech_stack>');
+      expect(content).toContain('<mode>speed</mode>');
+    });
+  });
+});