jettypod 4.4.0 → 4.4.2

package/skills-templates/chore-mode/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: chore-mode
+description: Guide implementation of standalone chores with type-appropriate guidance, verification steps, and test handling. Receives enriched context from chore-planning and executes with iteration until verification passes.
+---
+
+# Chore Mode Skill
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  Standalone Chore Execution                                         │
+│                                                                      │
+│  chore-planning → [CHORE MODE] → Done                               │
+│                    ▲▲▲▲▲▲▲▲▲▲▲                                      │
+│                    YOU ARE HERE                                      │
+│                                                                      │
+│  Chores are focused tasks - no speed/stable/production progression. │
+│  Execute once with type-appropriate verification, then done.        │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+Guides Claude Code through chore execution with type-specific guidance, test handling, and verification criteria from the chore taxonomy.
+
+## Instructions
+
+When this skill is activated, you are executing a standalone chore. The chore-planning skill has already classified the type and built enriched context. Follow this structured approach:
+
+### Overview
+
+**Chore Mode Goal:** Execute the chore according to type-specific guidance and verify completion using taxonomy criteria.
+
+**Key Principles:**
+- **Type-aware execution** - Different chore types have different test handling and verification
+- **Guided verification** - Use taxonomy verification checklist, not arbitrary checks
+- **Iteration with limits** - Max 5 iterations to achieve verification
+- **No mode progression** - Chores don't have speed/stable/production phases
+
+**Chore Types Quick Reference:**
+
+| Type | Test Handling | Key Constraint |
+|------|---------------|----------------|
+| refactor | Affected tests only | Do NOT modify test assertions |
+| dependency | Full test suite | Check for deprecation warnings |
+| cleanup | Affected tests | Verify code is actually unused |
+| tooling | CI/manual verification | Focus on verification over unit tests |
+
+---
+
+## Implementation Steps
+
+### Step 1: Receive and Display Context
+
+**Your task:** Acknowledge the context passed from chore-planning.
+
+You will receive:
+- `choreContext.chore` - Chore ID, title, description
+- `choreContext.classification` - Type and confidence
+- `choreContext.guidance` - Scope, verification, testHandling from taxonomy
+- `choreContext.implementationPlan` - Files to modify, affected tests
+
+**Display:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔧 Chore Mode: [Chore Title]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Type: [TYPE] (confidence: [high/medium/low])
+Chore ID: #[id]
+
+Implementation Plan:
+• Files to modify: [list from context]
+• Affected tests: [list from context]
+```
+
+**Move to Step 2 automatically.**
+
+### Step 2: Create Worktree
+
+**Your task:** Create an isolated worktree for this chore.
+
+```bash
+jettypod work start [chore-id]
+```
+
+This creates a worktree at `.jettypod-work/[id]-[title-slug]` and switches to a new branch.
+
+**Display:**
+
+```
+📁 Worktree created: .jettypod-work/[id]-[title-slug]
+Branch: chore-[id]-[title-slug]
+```
+
+**Move to Step 3 automatically.**
+
+### Step 3: Establish Test Baseline
+
+**Your task:** Run tests to establish baseline before making changes.
+
+**Test handling varies by type:**
+
+**For REFACTOR:**
+```bash
+# Run only affected module tests
+npm test -- [affected-test-patterns]
+```
+
+**For DEPENDENCY:**
+```bash
+# Run full test suite
+npm test
+```
+
+**For CLEANUP:**
+```bash
+# Run affected tests
+npm test -- [affected-test-patterns]
+```
+
+**For TOOLING:**
+```bash
+# Run CI pipeline or specific verification
+# (may not have unit tests)
+```
+
+**Display:**
+
+```
+🧪 Establishing test baseline...
+
+Baseline Result:
+  Tests: [X] passing / [Y] total
+  Execution time: [Z]s
+
+✅ Baseline established - all tests passing
+```
+
+**CRITICAL:** If baseline tests fail, STOP. Fix existing failures before proceeding with chore work.
+
+**Move to Step 4 automatically.**
+
+### Step 4: Display Type-Specific Guidance
+
+**Your task:** Display warnings and constraints based on chore type.
+
+**Load guidance from taxonomy:**
+
+```javascript
+const { getGuidance } = require('./lib/chore-taxonomy');
+const guidance = getGuidance('[chore-type]');
+```
+
+**Display type-specific warnings:**
+
+**For REFACTOR:**
+```
+⚠️  REFACTOR CONSTRAINTS:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+• All existing tests MUST pass WITHOUT modification
+• If tests fail, the refactor broke behavior - FIX THE CODE, not the tests
+• No new functionality - this is restructuring only
+• Behavior must be preserved exactly
+```
+
+**For DEPENDENCY:**
+```
+⚠️  DEPENDENCY CONSTRAINTS:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+• Run FULL test suite to catch regressions
+• Check for deprecation warnings after update
+• Review changelog for breaking changes
+• Update code if API changed
+```
+
+**For CLEANUP:**
+```
+⚠️  CLEANUP CONSTRAINTS:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+• VERIFY code is actually unused before deleting
+• Search for all references (grep for function names)
+• Remove tests ONLY if they test deleted code
+• Check for dynamic references (string-based imports)
+```
+
+**For TOOLING:**
+```
+⚠️  TOOLING CONSTRAINTS:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+• Verify via CI run or manual testing
+• Focus on verification over unit testing
+• Document current behavior before changes
+• Plan rollback strategy
+```
+
+**Move to Step 5 automatically.**
+
+### Step 5: Execute with Iteration
+
+**Your task:** Make changes and iterate until tests pass. Max 5 iterations.
+
+```
+━━━ Iteration [N]/5 ━━━
+
+✍️  Making changes...
+[Describe what you're changing]
+
+🧪 Running tests...
+```
+
+**On each iteration:**
+1. Make focused changes based on implementation plan
+2. Run appropriate tests (type-dependent)
+3. Check results
+
+**Display progress:**
+
+```
+📊 Progress: [X]/[Y] tests passing
+
+✅ Newly passing:
+  • [test name]
+
+❌ Still failing:
+  • [test name]: [brief error]
+
+🔧 Next: [what you'll fix]
+```
+
+**Exit conditions:**
+- ✅ All tests pass → Move to Step 6
+- ❌ Max iterations reached → Display failure, ask user for guidance
+
+**On max iterations:**
+
+```
+⚠️  Maximum iterations (5) reached
+
+Final Progress: [X]/[Y] tests passing
+
+Still failing:
+  • [test name]: [error]
+
+Options:
+1. Review implementation approach
+2. Break into smaller changes
+3. Get user guidance
+
+What would you like to do?
+```
+
+**STOP and wait for user input if max iterations reached.**
+
+### Step 6: Run Verification Checklist
+
+**Your task:** Run through type-specific verification criteria from taxonomy.
+
+**Load verification from taxonomy:**
+
+```javascript
+const { getGuidance } = require('./lib/chore-taxonomy');
+const guidance = getGuidance('[chore-type]');
+// guidance.verification contains the checklist
+```
+
+**Display and verify each item:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔍 Verification Checklist
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[✅/❌] All existing tests pass without modification
+[✅/❌] No new functionality added
+[✅/❌] Code review confirms behavior preservation
+[✅/❌] Performance is not degraded
+```
+
+**Verification methods:**
+- **Tests pass**: Run `npm test` and check exit code
+- **No new functionality**: Review diff for new features
+- **Behavior preservation**: Compare before/after behavior
+- **Performance**: Run benchmarks if applicable
+
+**If any verification fails:**
+
+```
+❌ Verification failed:
+  • [failed item]: [reason]
+
+Returning to iteration loop...
+```
+
+Go back to Step 5 to fix issues.
+
+**If all verification passes → Move to Step 7.**
+
+### Step 7: Complete and Merge
+
+**Your task:** Commit changes and merge to main.
+
+```bash
+# Stage and commit
+git add .
+git commit -m "chore: [brief description]"
+git push
+
+# Merge to main (auto-marks chore done)
+jettypod work merge
+```
+
+**Display:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Chore Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Type: [TYPE]
+Iterations: [N]/5
+Tests: [X]/[Y] passing
+
+Verification:
+✅ All existing tests pass without modification
+✅ No new functionality added
+✅ Code review confirms behavior preservation
+✅ Performance is not degraded
+
+Merged to main. Chore #[id] marked done.
+```
+
+**End skill.**
+
+---
+
+## Error Handling
+
+### Baseline Tests Fail
+```
+❌ Cannot proceed - baseline tests failing
+
+[X] tests failing before chore work started.
+Fix existing test failures before proceeding.
+
+Failing tests:
+  • [test name]: [error]
+```
+
+### Verification Loop
+If verification fails repeatedly (3+ times on same item):
+```
+⚠️  Verification stuck on: [item]
+
+This has failed [N] times. Options:
+1. Review the implementation approach
+2. Check if this verification is applicable
+3. Ask user for guidance
+```
+
+### Worktree Issues
+```
+❌ Worktree creation failed
+
+Error: [message]
+
+Try:
+  jettypod work cleanup
+  jettypod work start [chore-id]
+```
+
+---
+
+## Type Reference
+
+### REFACTOR
+- **Goal:** Restructure code without changing behavior
+- **Tests:** Affected modules only
+- **Key rule:** NEVER modify test assertions
+- **Verification:** Tests pass, behavior unchanged
+
+### DEPENDENCY
+- **Goal:** Update packages safely
+- **Tests:** Full suite
+- **Key rule:** Check changelogs for breaking changes
+- **Verification:** Tests pass, no deprecation warnings
+
+### CLEANUP
+- **Goal:** Remove unused code
+- **Tests:** Affected modules
+- **Key rule:** Verify code is actually unused
+- **Verification:** No broken references, tests pass
+
+### TOOLING
+- **Goal:** Improve build/CI/dev tools
+- **Tests:** CI pipeline or manual
+- **Key rule:** Plan rollback strategy
+- **Verification:** CI passes, workflows work

package/skills-templates/chore-mode/verification.js

@@ -0,0 +1,255 @@
+/**
+ * Type-specific verification runner for chore-mode skill
+ * Runs verification checklist from chore taxonomy based on chore type
+ */
+
+const { getGuidance, CHORE_TYPES } = require('../../../lib/chore-taxonomy');
+
+/**
+ * Create a verification check result
+ *
+ * @param {string} description - What is being verified
+ * @param {boolean} passed - Whether the check passed
+ * @param {string} [details] - Additional details or failure reason
+ * @returns {{description: string, passed: boolean, details?: string}}
+ */
+function createCheck(description, passed, details = null) {
+  const check = { description, passed };
+  if (details) check.details = details;
+  return check;
+}
+
+/**
+ * Run all verification checks for a chore type
+ *
+ * @param {string} type - Chore type (refactor, dependency, cleanup, tooling)
+ * @param {object} context - Context about the chore execution
+ * @param {object} context.testResult - Test execution result
+ * @param {boolean} context.testResult.passed - Whether tests passed
+ * @param {number} context.testResult.total - Total tests run
+ * @param {boolean} [context.testsModified] - Whether test assertions were changed
+ * @param {boolean} [context.newFunctionalityAdded] - Whether new features were added
+ * @param {string[]} [context.deprecationWarnings] - Any deprecation warnings found
+ * @param {boolean} [context.unusedCodeVerified] - Whether code was verified unused
+ * @param {boolean} [context.ciPassed] - Whether CI pipeline passed
+ * @returns {{passed: boolean, checks: Array<{description: string, passed: boolean, details?: string}>}}
+ */
+function runVerificationChecklist(type, context = {}) {
+  const guidance = getGuidance(type);
+  const checks = [];
+  let allPassed = true;
+
+  // Run type-specific verification based on taxonomy criteria
+  switch (type) {
+    case CHORE_TYPES.REFACTOR:
+      checks.push(...runRefactorChecks(guidance, context));
+      break;
+
+    case CHORE_TYPES.DEPENDENCY:
+      checks.push(...runDependencyChecks(guidance, context));
+      break;
+
+    case CHORE_TYPES.CLEANUP:
+      checks.push(...runCleanupChecks(guidance, context));
+      break;
+
+    case CHORE_TYPES.TOOLING:
+      checks.push(...runToolingChecks(guidance, context));
+      break;
+
+    default:
+      checks.push(createCheck(
+        'Valid chore type',
+        false,
+        `Unknown type: ${type}`
+      ));
+  }
+
+  // Calculate overall pass/fail
+  allPassed = checks.every(check => check.passed);
+
+  return {
+    passed: allPassed,
+    checks
+  };
+}
+
+/**
+ * Run refactor-specific verification checks
+ */
+function runRefactorChecks(guidance, context) {
+  const checks = [];
+
+  // "All existing tests pass without modification"
+  checks.push(createCheck(
+    'All existing tests pass without modification',
+    context.testResult?.passed === true,
+    context.testResult?.passed ? null : 'Tests failed - refactor may have broken behavior'
+  ));
+
+  // Check if tests were modified (should NOT be)
+  checks.push(createCheck(
+    'No test assertions modified',
+    context.testsModified !== true,
+    context.testsModified ? 'Test assertions were changed - this violates refactor rules' : null
+  ));
+
+  // "No new functionality added"
+  checks.push(createCheck(
+    'No new functionality added',
+    context.newFunctionalityAdded !== true,
+    context.newFunctionalityAdded ? 'New functionality detected - this should be a feature, not a refactor' : null
+  ));
+
+  // "Performance is not degraded" - assumed pass unless context indicates otherwise
+  checks.push(createCheck(
+    'Performance not degraded',
+    context.performanceDegraded !== true,
+    context.performanceDegraded ? 'Performance regression detected' : null
+  ));
+
+  return checks;
+}
+
+/**
+ * Run dependency-specific verification checks
+ */
+function runDependencyChecks(guidance, context) {
+  const checks = [];
+
+  // "All tests pass after update"
+  checks.push(createCheck(
+    'All tests pass after update',
+    context.testResult?.passed === true,
+    context.testResult?.passed ? null : 'Tests failed after dependency update'
+  ));
+
+  // "Application builds successfully" - assumed from test pass
+  checks.push(createCheck(
+    'Application builds successfully',
+    context.buildPassed !== false,
+    context.buildPassed === false ? 'Build failed' : null
+  ));
+
+  // "No new deprecation warnings"
+  const hasDeprecations = context.deprecationWarnings && context.deprecationWarnings.length > 0;
+  checks.push(createCheck(
+    'No new deprecation warnings (or documented)',
+    !hasDeprecations || context.deprecationsDocumented === true,
+    hasDeprecations && !context.deprecationsDocumented
+      ? `Found ${context.deprecationWarnings.length} deprecation warnings`
+      : null
+  ));
+
+  return checks;
+}
+
+/**
+ * Run cleanup-specific verification checks
+ */
+function runCleanupChecks(guidance, context) {
+  const checks = [];
+
+  // "All tests still pass"
+  checks.push(createCheck(
+    'All tests still pass',
+    context.testResult?.passed === true,
+    context.testResult?.passed ? null : 'Tests failed after cleanup'
+  ));
+
+  // "No broken imports or references"
+  checks.push(createCheck(
+    'No broken imports or references',
+    context.brokenReferences !== true,
+    context.brokenReferences ? 'Broken references found' : null
+  ));
+
+  // "Removed code was actually unused"
+  checks.push(createCheck(
+    'Removed code was verified unused',
+    context.unusedCodeVerified === true,
+    context.unusedCodeVerified ? null : 'Code usage was not verified before removal'
+  ));
+
+  return checks;
+}
+
+/**
+ * Run tooling-specific verification checks
+ */
+function runToolingChecks(guidance, context) {
+  const checks = [];
+
+  // "CI pipeline passes"
+  checks.push(createCheck(
+    'CI pipeline passes',
+    context.ciPassed === true,
+    context.ciPassed ? null : 'CI not verified or failed'
+  ));
+
+  // "Build completes successfully"
+  checks.push(createCheck(
+    'Build completes successfully',
+    context.buildPassed !== false,
+    context.buildPassed === false ? 'Build failed' : null
+  ));
+
+  // "No regression in build times or developer experience"
+  checks.push(createCheck(
+    'No regression in build times/DX',
+    context.dxRegression !== true,
+    context.dxRegression ? 'Developer experience regression detected' : null
+  ));
+
+  return checks;
+}
+
+/**
+ * Format verification results for display
+ *
+ * @param {{passed: boolean, checks: Array}} result - Verification result
+ * @returns {string} Formatted string for display
+ */
+function formatVerificationResult(result) {
+  const lines = [];
+  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  lines.push('🔍 Verification Checklist');
+  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  lines.push('');
+
+  for (const check of result.checks) {
+    const icon = check.passed ? '✅' : '❌';
+    lines.push(`${icon} ${check.description}`);
+    if (check.details) {
+      lines.push(`   └─ ${check.details}`);
+    }
+  }
+
+  lines.push('');
+  if (result.passed) {
+    lines.push('✅ All verification checks passed');
+  } else {
+    const failedCount = result.checks.filter(c => !c.passed).length;
+    lines.push(`❌ ${failedCount} verification check(s) failed`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Get verification criteria from taxonomy for display
+ *
+ * @param {string} type - Chore type
+ * @returns {string[]} Array of verification criteria strings
+ */
+function getVerificationCriteria(type) {
+  const guidance = getGuidance(type);
+  return guidance.verification || [];
+}
+
+module.exports = {
+  runVerificationChecklist,
+  formatVerificationResult,
+  getVerificationCriteria,
+  createCheck
+};