jettypod 4.1.0 → 4.1.1

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

@@ -0,0 +1,369 @@
+---
+name: production-mode
+description: Guide implementation of production mode chores with production standards validation. Use when user starts work on a production mode chore. Detects context (Scenario A/B/C), validates/generates scenarios, and implements production hardening comprehensively.
+---
+
+# Production Mode Skill
+
+Guides Claude Code through production mode implementation with focus on security, scale, and compliance. Autonomous execution - Claude Code writes the code.
+
+## Instructions
+
+When this skill is activated, you are helping implement a production mode chore to add production hardening. Follow this structured approach:
+
+### Overview
+
+**Production Mode Goal:** Harden features for production deployment with security, performance, and compliance standards.
+
+**CRITICAL CONTEXT DETECTION:**
+- Production mode has **3 different starting scenarios** (A/B/C)
+- **Must detect context first** before proceeding
+- Different workflows for each scenario
+
+**Key Principles:**
+- **Context-aware execution** - adapt to Scenario A/B/C
+- **Standards-driven** - use production standards from external-transition
+- **Autonomous execution** - Claude Code writes code, user confirms approach
+- **Comprehensive hardening** - security, performance, compliance, infrastructure
+
+**User Profile:** May not know how to code - Claude Code does the implementation autonomously.
+
+---
+
+## Implementation Steps
+
+### Step 0: Detect Production Context (CRITICAL FIRST STEP)
+
+**MUST RUN FIRST:** Detect which scenario applies to this feature.
+
+**Code to detect context:**
+
+```javascript
+const { detectContext } = require('../../lib/production-context-detector');
+const { getCurrentWork } = require('../../lib/current-work');
+const { getDb } = require('../../lib/database');
+
+try {
+  const currentWork = getCurrentWork();
+
+  if (!currentWork) {
+    console.error('❌ No current work found. Run: jettypod work start <chore-id>');
+    return;
+  }
+
+  if (!currentWork.parent_id) {
+    console.error('❌ Current work has no parent feature.');
+    return;
+  }
+
+  const featureId = currentWork.parent_id;
+  const scenario = await detectContext(featureId);
+
+  console.log(`📋 Detected: ${scenario}`);
+
+  // Proceed with appropriate workflow
+  if (scenario === 'SCENARIO_A') {
+    // Fresh from stable mode - quick validation
+  } else if (scenario === 'SCENARIO_B') {
+    // Gap in time - re-validation
+  } else {
+    // Scenario C - generate from standards
+  }
+} catch (err) {
+  console.error('❌ Context detection failed:', err.message);
+  return;
+}
+```
+
+**Three Scenarios:**
+
+**Scenario A: Fresh from Stable (Hot Context)**
+- Production scenarios exist
+- Production chores exist
+- Completed stable ≤ 1 day ago
+- **Workflow:** Quick validation → fill gaps → implement
+
+**Scenario B: Gap in Time (Cold Context)**
+- Production scenarios exist
+- Production chores exist
+- Completed stable > 1 day ago OR project state changed
+- **Workflow:** Re-validate → update scenarios → implement
+
+**Scenario C: Post External-Transition (New Infrastructure)**
+- NO production scenarios exist
+- NO production chores exist
+- **Workflow:** Generate scenarios → create chores → implement
+
+---
+
+### Step 1: Read Production Standards
+
+**For all scenarios:** Read production standards file.
+
+```javascript
+const { readStandards, standardsFileExists } = require('../../lib/production-standards-reader');
+
+try {
+  if (!standardsFileExists()) {
+    console.error('❌ Production standards file not found.');
+    console.log('Run external-transition first to generate production standards.');
+    return;
+  }
+
+  const standards = await readStandards();
+  console.log(`📋 Loaded ${standards.standards.length} production standards`);
+  console.log(`Preset: ${standards.preset}`);
+
+  // Show domains
+  const domains = await getDomains();
+  console.log(`Domains: ${domains.join(', ')}`);
+} catch (err) {
+  console.error('❌ Failed to read production standards:', err.message);
+  return;
+}
+```
+
+---
+
+### Step 2A: Validate Scenarios (Scenario A - Hot Context)
+
+**For Scenario A only:** Quick validation of existing scenarios.
+
+```javascript
+const { validateScenarios } = require('../../lib/production-scenario-validator');
+const { getDb } = require('../../lib/database');
+
+try {
+  // Get feature scenario file
+  const db = getDb();
+  const feature = await new Promise((resolve, reject) => {
+    db.get('SELECT * FROM work_items WHERE id = ?', [featureId], (err, row) => {
+      if (err) reject(err);
+      resolve(row);
+    });
+  });
+
+  if (!feature.scenario_file) {
+    console.error('❌ Feature has no scenario file.');
+    return;
+  }
+
+  // Validate scenarios against standards
+  const validation = await validateScenarios(feature.scenario_file, standards);
+
+  console.log(`✅ Validation complete:`);
+  console.log(`  - Covered: ${validation.covered}/${validation.total} standards`);
+  console.log(`  - Gaps: ${validation.gaps.length}`);
+
+  if (validation.hasGaps) {
+    console.log('\n⚠️  Missing scenarios for:');
+    validation.gaps.forEach(gap => {
+      console.log(`  - ${gap.domain}: ${gap.standardId}`);
+      console.log(`    ${gap.reasoning}`);
+    });
+
+    // Generate and append missing scenarios
+    const { generateScenariosFromStandards } = require('../../lib/production-scenario-generator');
+    const { appendScenarios } = require('../../lib/production-scenario-appender');
+
+    const missingStandards = { standards: validation.gaps };
+    const newScenarios = await generateScenariosFromStandards(missingStandards);
+
+    await appendScenarios(feature.scenario_file, newScenarios);
+    console.log(`✅ Added ${newScenarios.length} missing scenarios`);
+  } else {
+    console.log('✅ All standards are covered by existing scenarios');
+  }
+} catch (err) {
+  console.error('❌ Validation failed:', err.message);
+  return;
+}
+```
+
+---
+
+### Step 2B: Re-Validate Scenarios (Scenario B - Cold Context)
+
+**For Scenario B only:** Re-validate with current standards.
+
+```javascript
+const { validateScenarios } = require('../../lib/production-scenario-validator');
+const config = require('../../lib/config');
+
+try {
+  console.log('🔄 Re-validating scenarios against current standards...');
+
+  // Check if project state changed
+  const projectConfig = config.read();
+  console.log(`Project state: ${projectConfig.project_state}`);
+
+  // Get feature scenario file
+  const db = getDb();
+  const feature = await new Promise((resolve, reject) => {
+    db.get('SELECT * FROM work_items WHERE id = ?', [featureId], (err, row) => {
+      if (err) reject(err);
+      resolve(row);
+    });
+  });
+
+  // Validate scenarios
+  const validation = await validateScenarios(feature.scenario_file, standards);
+
+  console.log(`✅ Re-validation complete:`);
+  console.log(`  - Covered: ${validation.covered}/${validation.total} standards`);
+  console.log(`  - New gaps: ${validation.gaps.length}`);
+
+  if (validation.hasGaps) {
+    console.log('\n⚠️  Standards added/changed since last run:');
+    validation.gaps.forEach(gap => {
+      console.log(`  - ${gap.domain}: ${gap.standardId}`);
+    });
+
+    // Generate and append missing scenarios
+    const { generateScenariosFromStandards } = require('../../lib/production-scenario-generator');
+    const { appendScenarios } = require('../../lib/production-scenario-appender');
+
+    const missingStandards = { standards: validation.gaps };
+    const newScenarios = await generateScenariosFromStandards(missingStandards);
+
+    await appendScenarios(feature.scenario_file, newScenarios);
+    console.log(`✅ Updated with ${newScenarios.length} new scenarios`);
+  }
+} catch (err) {
+  console.error('❌ Re-validation failed:', err.message);
+  return;
+}
+```
+
+---
+
+### Step 2C: Generate Scenarios (Scenario C - Post-Transition)
+
+**For Scenario C only:** Generate production scenarios from standards.
+
+```javascript
+const { generateScenariosFromStandards } = require('../../lib/production-scenario-generator');
+const { appendScenarios } = require('../../lib/production-scenario-appender');
+const { getDb } = require('../../lib/database');
+
+try {
+  console.log('✨ Generating production scenarios from standards...');
+
+  // Get feature
+  const db = getDb();
+  const feature = await new Promise((resolve, reject) => {
+    db.get('SELECT * FROM work_items WHERE id = ?', [featureId], (err, row) => {
+      if (err) reject(err);
+      resolve(row);
+    });
+  });
+
+  if (!feature.scenario_file) {
+    console.error('❌ Feature has no scenario file.');
+    return;
+  }
+
+  // Generate scenarios
+  const scenarios = await generateScenariosFromStandards(standards);
+
+  console.log(`✅ Generated ${scenarios.length} production scenarios`);
+  console.log('Domains covered:', [...new Set(standards.standards.map(s => s.domain))].join(', '));
+
+  // Append to feature file
+  await appendScenarios(feature.scenario_file, scenarios);
+  console.log(`✅ Appended scenarios to ${feature.scenario_file}`);
+
+  // Create production chores if none exist
+  const { generateChoresFromStandards } = require('../../lib/production-chore-generator');
+  const chores = generateChoresFromStandards(standards, feature.title);
+
+  console.log(`\n📋 Proposed ${chores.length} production chores:`);
+  chores.forEach((chore, i) => {
+    console.log(`\n${i + 1}. ${chore.title}`);
+    console.log(`   ${chore.description.split('\n')[0]}`);
+  });
+
+  console.log('\n✅ Production scenarios ready. Create chores to implement them.');
+} catch (err) {
+  console.error('❌ Scenario generation failed:', err.message);
+  return;
+}
+```
+
+---
+
+### Step 3: Implement Production Chore
+
+**For all scenarios:** Implement the current production chore.
+
+```javascript
+const { getCurrentWork } = require('../../lib/current-work');
+const fs = require('fs');
+
+try {
+  const currentWork = getCurrentWork();
+
+  console.log(`\n🚀 Implementing: ${currentWork.title}`);
+  console.log(`Description: ${currentWork.description}`);
+
+  // Parse chore to understand which standard to implement
+  // Implementation follows the acceptance criteria from the standard
+
+  // Example: If chore is about TLS enforcement
+  // 1. Read the standard's acceptance criteria
+  // 2. Implement code that satisfies the criteria
+  // 3. Add tests based on scenario steps
+
+  console.log('\n✅ Implementation complete');
+  console.log('Run: npx cucumber-js to verify scenarios pass');
+} catch (err) {
+  console.error('❌ Implementation failed:', err.message);
+  return;
+}
+```
+
+---
+
+## Key Differences from Stable Mode
+
+**Stable Mode:**
+- Adds error handling to speed code
+- Validates inputs, handles edge cases
+- Makes existing features robust
+
+**Production Mode:**
+- Hardens features for production deployment
+- Implements security, scale, compliance standards
+- Adds monitoring, backup, failover capabilities
+- Standards-driven (not just adding error handling)
+
+**Example:**
+
+**Stable Mode Chore:** "Add error handling to login feature"
+→ Validates email format, handles network errors, shows error messages
+
+**Production Mode Chore:** "Add security hardening to login feature"
+→ Rate limiting, brute force protection, MFA support, audit logging
+
+---
+
+## Validation
+
+Before completing production mode, ensure:
+- [ ] Context detected correctly (A/B/C)
+- [ ] Production standards read successfully
+- [ ] All production scenarios pass
+- [ ] Security measures implemented per standards
+- [ ] Performance targets met per standards
+- [ ] Compliance requirements satisfied
+- [ ] Monitoring and observability added
+- [ ] Documentation updated
+
+---
+
+## Next Steps After Production Mode
+
+Once all production chores complete:
+1. Feature is production-ready
+2. Can be deployed to external environment
+3. Meets all standards for scale, security, compliance

package/test-tmp/external-transition-1762982642301/.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".jettypod/hooks/protect-claude-md.js"
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".jettypod/hooks/protect-claude-md.js"
+          }
+        ]
+      }
+    ]
+  }
+}

package/test-tmp/external-transition-1762982642301/.claude/skills/epic-planning/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: epic-planning
+description: Guide epic planning with feature brainstorming and optional architectural decision prototyping. Use when user asks to plan an epic, mentions planning features for an epic, says "help me plan epic", or when they just created an epic and want to break it down into features.
+---
+
+# Epic Planning Skill
+
+Guides Claude through comprehensive epic planning including feature identification and architectural decisions.
+
+## Instructions
+
+When this skill is activated, you are helping plan an epic. Follow this structured approach:
+
+### Step 1: Understand the Epic
+
+You'll receive context about the epic being planned. Review:
+- Epic title and description
+- Project context
+- Any parent context
+
+### Step 2: Check Existing Features and Decisions
+
+**CRITICAL:** Before suggesting features or approaches, check what already exists:
+
+**Check for existing features:**
+```bash
+node jettypod.js backlog | grep -A 20 "Epic Name"
+```
+
+If features already exist, acknowledge them and skip to Step 4 (Architectural Decision).
+
+**Check for existing decisions:**
+```bash
+node -e "const { showDecisionsForEpic } = require('./features/decisions/index.js'); showDecisionsForEpic(epicId)"
+```
+
+If decisions exist, present them to the user:
+
+```
+🎯 **Existing Architectural Decisions for This Epic:**
+
+[For each decision:]
+- **[Aspect]:** [Decision]
+  *Rationale:* [Why this was chosen]
+  *Decided:* [Date]
+
+These decisions were made previously. Before we continue:
+1. Do these decisions still apply?
+2. Should we revisit any of them?
+3. Are there additional aspects we need to decide?
+```
+
+Only proceed with suggesting new architectural options if:
+- No decisions exist yet, OR
+- User confirms decisions need to be revisited, OR
+- User identifies new aspects to decide
+
+### Step 3: Brainstorm Features (Skip if Features Already Exist)
+
+Based on the epic's purpose, suggest features that belong in this epic:
+
+```
+I'll help you plan the features for this epic.
+
+Based on [epic name], here are the features I recommend:
+
+**Feature 1: [Name]** - [Brief description of what users can do]
+**Feature 2: [Name]** - [Brief description]
+**Feature 3: [Name]** - [Brief description]
+...
+
+**Questions:**
+- [Any clarifying questions about scope]
+- [Missing features to consider]
+
+What features should we include? What am I missing?
+```
+
+### Step 4: Architectural Decision (Optional)
+
+After features are defined, ask if this epic needs a shared technical approach:
+
+```
+**Architectural question:** Does this epic need a shared technical decision?
+
+For example:
+- Which library/framework for this capability?
+- What data structure or protocol?
+- What architectural pattern?
+
+Examples where architectural decisions matter:
+- Real-time features: WebSockets vs SSE vs polling?
+- Auth system: Which auth library and token strategy?
+- Data sync: Optimistic vs pessimistic locking?
+
+Should we explore different architectural approaches?
+```
+
+### Step 5A: If Architectural Decision Needed
+
+If the epic needs architectural decision, suggest exactly 3 approaches:
+
+```
+Here are 3 different architectural approaches for [epic name]:
+
+**Option 1: [Simple/Conservative approach name]**
+- **Pros**: ✅ [2-3 advantages - proven, reliable, fast to implement]
+- **Cons**: ❌ [2-3 trade-offs - limitations, constraints]
+- **Technical Impact**: [How this affects the features in this epic]
+
+**Option 2: [Balanced approach name]**
+- **Pros**: ✅ [2-3 advantages - good balance]
+- **Cons**: ❌ [2-3 trade-offs]
+- **Technical Impact**: [How this affects the features in this epic]
+
+**Option 3: [Advanced/Modern approach name]**
+- **Pros**: ✅ [2-3 advantages - powerful, flexible]
+- **Cons**: ❌ [2-3 trade-offs - complexity, learning curve]
+- **Technical Impact**: [How this affects the features in this epic]
+
+**Additional approaches considered but not recommended:**
+- *[Alternative 1]*: [Brief] - Not selected because [reason]
+- *[Alternative 2]*: [Brief] - Not selected because [reason]
+
+Would you like me to create working prototypes of these architectural approaches?
+```
+
+### Step 5B: If Prototyping Needed
+
+If user wants to prototype approaches:
+
+1. Build 2-3 prototype approaches in `/prototypes/epic-[id]-[approach-name]/`
+2. Each prototype should demonstrate the architectural difference
+3. **Add prototype header**:
+   ```
+   // Prototype: Epic [epic-id] - [approach name]
+   // Created: [date]
+   // Purpose: Demonstrate [architectural aspect]
+   // Decision: [to be filled after testing]
+   ```
+4. After user tests, help them choose the winner
+5. Document the decision and rationale
+
+### Step 5C: If Approach Already Known
+
+If user already knows the approach or skips prototyping:
+
+```
+Which architectural approach works best for this epic?
+```
+
+Then record their decision.
+
+### Step 6: Create Features and Complete Discovery
+
+Once features are defined and architectural decision is made (if needed):
+
+**CRITICAL: You must EXECUTE commands using the Bash tool. Do NOT just display them as text.**
+
+#### Step 6A: Create Features
+
+Use the Bash tool to create each feature:
+
+```javascript
+// For each feature, use Bash tool to execute:
+node jettypod.js work create feature "[Feature 1]" "[Description]" --parent=[epic-id]
+node jettypod.js work create feature "[Feature 2]" "[Description]" --parent=[epic-id]
+// etc.
+```
+
+Display to user as you create each one:
+```
+Creating features...
+✅ Created Feature #123: [Feature 1]
+✅ Created Feature #456: [Feature 2]
+```
+
+#### Step 6B: Record Architectural Decision (if applicable)
+
+If an architectural decision was made, propose the rationale to the user:
+
+```
+I'm going to record this architectural decision:
+
+Aspect: Architecture
+Decision: [architectural approach chosen]
+Rationale: [why this approach was selected]
+
+Does this rationale capture why you chose this approach? (You can edit it if needed)
+```
+
+**WAIT for user to confirm or provide edited rationale.**
+
+**CRITICAL: After user confirms, use Bash tool to EXECUTE the epic-implement command:**
+
+```javascript
+// Use Bash tool to execute:
+node jettypod.js work epic-implement [epic-id] \
+  --aspect="Architecture" \
+  --decision="[architectural approach chosen]" \
+  --rationale="[user's confirmed/edited rationale]"
+```
+
+**DO NOT display this as example text. EXECUTE IT using the Bash tool.**
+
+After execution succeeds, verify the decision was recorded and display:
+
+```
+✅ Architectural decision recorded
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 Epic Planning Complete!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Features created: [count]
+Architectural decision: Recorded
+
+**Next step:** Plan your first feature
+Run: jettypod work discover [feature-id]
+Or talk to Claude Code: "Let's do feature discovery for #[feature-id]"
+```
+
+## Key Principles
+
+1. **Feature brainstorming is always required** - Don't skip this even if architectural decision is clear
+2. **Architectural decision is optional** - Not all epics need one (e.g., "Q1 Goals" is just grouping)
+3. **Always suggest exactly 3 options** when architectural decision needed - Simple/Conservative, Balanced, Advanced
+4. **Be specific about features** - Each feature should be user-facing capability
+5. **Use the Approach Suggestion template** - Pros, Cons, Technical Impact format
+6. **Suggest next step** - Always end with clear guidance on what to do next
+7. **Use jettypod commands** - Create features using jettypod CLI, record decisions with epic-implement
+
+## Example: Epic with Architectural Decision
+
+Epic: "Real-time Collaboration"
+
+**Features brainstormed:**
+- Live cursor tracking
+- Concurrent editing with conflict resolution
+- Presence indicators
+- Real-time chat
+
+**Architectural approaches suggested:**
+
+**Option 1: Long Polling (REST)**
+- **Pros**: ✅ Simple, works with all proxies, uses existing HTTP infrastructure
+- **Cons**: ❌ Higher latency (1-2s), more server load, inefficient for high-frequency updates
+- **Technical Impact**: Each feature polls independently, easy to implement per feature
+
+**Option 2: Server-Sent Events (SSE)**
+- **Pros**: ✅ Lightweight, auto-reconnection, efficient one-way streaming
+- **Cons**: ❌ One-direction only (server→client), limited browser connections (6 per domain)
+- **Technical Impact**: Good for cursor/presence, requires separate POST for edits
+
+**Option 3: WebSockets (Socket.io)**
+- **Pros**: ✅ Bidirectional, low latency (<100ms), perfect for real-time, fallback support
+- **Cons**: ❌ More complex infrastructure, requires sticky sessions, WebSocket proxies needed
+- **Technical Impact**: All features use unified connection, best UX but infrastructure complexity
+
+**Additional approaches considered:**
+- *WebRTC Data Channels*: Peer-to-peer, low latency - Not selected due to NAT/firewall traversal complexity
+- *GraphQL Subscriptions*: Good for selective updates - Not selected as overkill for this use case
+
+**User choice:** Option 3 (WebSockets with Socket.io)
+
+**Rationale confirmation:**
+Claude proposes: "Bidirectional real-time updates needed for collaboration, Socket.io provides fallbacks and auto-reconnection"
+User confirms: "Yes, that's right"
+
+**Command run:**
+```bash
+jettypod work epic-implement 5 \
+  --aspect="Architecture" \
+  --decision="WebSockets with Socket.io" \
+  --rationale="Bidirectional real-time updates needed for collaboration, Socket.io provides fallbacks and auto-reconnection"
+```
+
+## Example: Epic without Architectural Decision
+
+Epic: "User Management"
+
+**Features brainstormed:**
+- User registration
+- Profile editing
+- Password reset
+- Account deletion
+
+**Architectural decision:** None needed - these are independent features using existing auth system
+
+## Validation
+
+Before completing epic discovery, ensure:
+- [ ] At least 2-3 features identified
+- [ ] Features are user-facing capabilities (not technical tasks)
+- [ ] Architectural decision documented if needed
+- [ ] Features created in database
+- [ ] User knows next step .jettypod work discover [feature-id])