jettypod 4.4.12 → 4.4.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jettypod",
-  "version": "4.4.12",
+  "version": "4.4.13",
   "description": "AI-powered development workflow manager with TDD, BDD, and automatic test generation",
   "main": "jettypod.js",
   "bin": {

package/skills-templates/feature-planning/SKILL.md

@@ -183,7 +183,48 @@ User picks winner. Note their choice - you'll record it formally in Step 8 when
 
 **Proceed to Step 6.**
 
-### Step 6: Generate BDD Scenarios AND Step Definitions
+### Step 6: Define Integration Contract AND Generate BDD Scenarios
+
+**CRITICAL:** Before writing scenarios, you MUST define how users reach this feature. Features that pass tests but aren't integrated into the product are useless.
+
+#### Step 6A: Define Integration Contract
+
+**Ask yourself and document:**
+
+1. **Entry Point** - How does a user reach this feature?
+   - Web: URL/route (e.g., `/login`, `/dashboard/settings`)
+   - CLI: Command (e.g., `jettypod backlog`)
+   - UI: Button, link, menu item (e.g., "Login button in header")
+   - API: Endpoint that exposes this (e.g., `POST /api/auth/login`)
+
+2. **Caller Code** - What existing code must invoke/import the new feature?
+   - Which file imports it (e.g., `src/app/layout.tsx`)
+   - Which component/function renders or calls it
+   - Where it's registered/mounted (e.g., router config, command registry)
+
+3. **Integration Scenario** - A BDD scenario proving the feature is reachable
+   - Must start from an existing entry point users can access
+   - Must navigate/invoke to reach the new feature
+   - Proves the feature isn't an "island"
+
+**Display to user:**
+
+```
+📍 Integration Contract
+
+**Entry Point:** [How users reach this feature]
+**Caller Code:** [What existing code invokes this]
+**Integration Test:** [Scenario proving reachability]
+
+Example:
+- Entry Point: `/login` route
+- Caller Code: `src/app/layout.tsx` renders `<LoginButton>` in header, which links to `/login`
+- Integration Test: "Given I'm on the home page, When I click 'Sign In', Then I see the login form"
+```
+
+**WAIT for user to confirm or adjust the integration contract.**
+
+#### Step 6B: Generate BDD Scenarios AND Step Definitions
 
 **CRITICAL:** BDD scenarios and step definitions must ALWAYS be created together. Never create scenarios without step definitions.
 
@@ -198,7 +239,8 @@ Based on chosen approach, generate:
 **A. Scenario file** at `features/[feature-slug].feature` using Write tool:
 
 1. **Create file** at `features/[feature-slug].feature` using Write tool
-2. **Include all "make it work" scenarios**:
+2. **FIRST scenario MUST be the Integration Scenario** from Step 6A (proves reachability)
+3. **Include all "make it work" scenarios**:
    - All success paths - required functionality AND optional features
    - Multiple valid workflows if the feature supports them
    - Success variations (different outcomes that are all correct)
@@ -239,6 +281,17 @@ Feature: [Feature Name]
   Epic: [Epic name if applicable]
   Approach: [Chosen approach name]
 
+  # Integration Contract:
+  # Entry Point: [from Step 6A]
+  # Caller Code: [from Step 6A]
+
+# INTEGRATION SCENARIO (REQUIRED - proves feature is reachable)
+Scenario: User can reach [feature] from [entry point]
+  Given I am on [existing entry point users can access]
+  When I [navigate/click/invoke to reach the feature]
+  Then I [see/access the feature]
+
+# FEATURE SCENARIOS (required + optional functionality)
 Scenario: [Core functionality - required workflow]
   Given [initial state]
   When [user takes main action]
@@ -250,7 +303,7 @@ Scenario: [Optional feature 1 - if applicable]
   When [user uses optional feature]
   Then [feature works correctly]
 
-# SPEED MODE: All success scenarios above (required + optional functionality)
+# SPEED MODE: All success scenarios above (integration + required + optional)
 # STABLE MODE: Will add error handling, validation failures, edge cases
 # These failure scenarios are added by stable-mode skill, NOT during feature discovery
 ```
@@ -263,6 +316,18 @@ Feature: Email/Password Login
   Epic: User Authentication
   Approach: Simple inline form
 
+  # Integration Contract:
+  # Entry Point: /login route
+  # Caller Code: src/app/layout.tsx renders LoginButton in header
+
+# INTEGRATION SCENARIO
+Scenario: User can reach login form from home page
+  Given I am on the home page
+  When I click the "Sign In" button in the header
+  Then I am on the login page
+  And I see the email and password fields
+
+# FEATURE SCENARIOS
 Scenario: User successfully logs in with valid credentials
   Given I am on the login page
   When I enter valid email and password
@@ -393,13 +458,19 @@ Display: "✅ BDD infrastructure validated - all steps have definitions"
 **CRITICAL:** After BDD validation passes, analyze the codebase and propose technical implementation chores. **DO NOT CREATE CHORES YET** - the feature must transition to implementation mode first (Step 8).
 
 **Your analysis should consider:**
-- The BDD scenarios (all success paths - required + optional features)
+- The BDD scenarios (integration + all success paths)
+- The Integration Contract from Step 6A
 - Existing codebase structure and patterns
 - Epic's architectural decisions (if any)
 - Tech stack and framework conventions
 - Which scenario steps each chore addresses
 - Similar code patterns to follow
 
+**REQUIRED: At least one chore MUST be an Integration Chore** that:
+- Wires the feature into the existing app
+- Makes the Integration Scenario pass
+- Modifies the caller code identified in Step 6A
+
 **Say to the user:**
 
 ```
@@ -409,7 +480,20 @@ Now let me analyze the codebase and propose implementation chores for speed mode
 
 Based on the scenario and my understanding of the codebase, here are the chores I recommend for speed mode:
 
-**Chore 1: [Technical task title]**
+**Chore 1: [Integration chore - wire feature into app]** ⚡ INTEGRATION
+- Why: Makes the feature reachable from [entry point]
+- Integration Contract:
+  • Entry point: [from Step 6A]
+  • Caller code to modify: [specific file/function]
+- Scenario steps addressed:
+  • [Integration scenario Given/When/Then steps]
+- Implementation guidance:
+  • Files to modify: [caller code files]
+  • What to add: [route, link, import, menu item, etc.]
+- Verification:
+  • Integration scenario passes (feature is reachable)
+
+**Chore 2: [Core functionality chore]**
 - Why: [What this accomplishes toward the scenario]
 - Scenario steps addressed:
   • [Which Given/When/Then steps this chore makes work]
@@ -420,20 +504,9 @@ Based on the scenario and my understanding of the codebase, here are the chores
 - Verification:
   • [Which step definitions should pass]
 
-**Chore 2: [Technical task title]**
-- Why: [What this accomplishes]
-- Scenario steps addressed:
-  • [Which steps]
-- Implementation guidance:
-  • Files to create/modify: [paths]
-  • Patterns to follow: [references]
-  • Key functions/components needed: [list]
-- Verification:
-  • [Which steps should pass]
-
 [etc.]
 
-These chores will make all success scenarios pass (required + optional features).
+These chores will make all scenarios pass (integration + required + optional features).
 
 Sound good? Any adjustments?
 ```
@@ -633,12 +706,15 @@ Before completing feature planning, ensure:
 - [ ] Epic's architectural decision is shown (if exists)
 - [ ] Exactly 3 approaches suggested
 - [ ] Winner chosen (with prototypes or without)
-- [ ] BDD scenarios written (all success paths)
+- [ ] **Integration Contract defined** (entry point, caller code, integration scenario)
+- [ ] **Integration Scenario is FIRST scenario** in feature file
+- [ ] BDD scenarios written (integration + all success paths)
 - [ ] Step definitions written for ALL scenario steps
 - [ ] Scenarios file exists at `features/[feature-slug].feature`
 - [ ] Step definitions file exists at `features/step_definitions/[feature-slug].steps.js`
 - [ ] BDD infrastructure validated with dry-run (Step 6.5)
 - [ ] Feature transitioned to implementation with `work implement`
+- [ ] **At least one Integration Chore created** (wires feature into app)
 - [ ] Speed mode chores created
 - [ ] First chore started with `work start [chore-id]` (Step 8D)
 - [ ] **Speed-mode skill invoked using Skill tool** (Step 8D)

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

@@ -50,9 +50,10 @@ When this skill is activated, you are helping implement a speed mode chore to ma
 
 ### Overview
 
-**Speed Mode Goal:** Make it work - implement ALL functionality (required + optional features) to make success scenarios pass, assuming everything works correctly.
+**Speed Mode Goal:** Make it work - implement ALL functionality (integration + required + optional features) to make success scenarios pass, assuming everything works correctly.
 
 **Key Principles:**
+- **Integration first** - ensure the feature is wired into the app and reachable (Integration Scenario must pass)
 - **Implement ALL features/functions** defined in scenarios - both required and optional functionality
 - **All success paths** - every workflow that should work when inputs are valid
 - **Assume success** - assume inputs are valid, files upload successfully, types are correct
@@ -67,6 +68,7 @@ When this skill is activated, you are helping implement a speed mode chore to ma
 <summary><strong>📋 Speed Mode Constraints (click to expand)</strong></summary>
 
 **What to implement:**
+- **Integration** - wire feature into the app so it's reachable (Integration Scenario)
 - ALL scoped functionality - required features AND optional features from all success scenarios
 - Multiple valid workflows if the feature supports them
 - Success variations (different outcomes that are all correct)
@@ -556,7 +558,25 @@ If the query returns no remaining chores, proceed to Step 7.
 
 This is the transition from speed mode to stable mode. Follow these phases in order.
 
-#### Step 7A: Merge Final Speed Chore
+#### Step 7A: Verify Integration Scenario Passes
+
+**CRITICAL: Before transitioning, verify the feature is actually integrated into the app.**
+
+```bash
+# Run ONLY the integration scenario (first scenario in the feature file)
+npx cucumber-js <scenario-file-path> --name "User can reach" --format progress
+```
+
+**If integration scenario FAILS:**
+- The feature exists but isn't wired into the app
+- Stop and fix integration before proceeding
+- Check: Is the route registered? Is the link/button added? Is the import in place?
+
+**If integration scenario PASSES:**
+- Feature is reachable by users
+- Proceed to Step 7B
+
+#### Step 7B: Merge Final Speed Chore
 
 ```bash
 # Commit changes in the worktree
@@ -568,7 +588,7 @@ jettypod work merge --with-transition
 
 After merge, you are on main branch. Ready to generate stable mode scenarios.
 
-#### Step 7B: Generate and Propose Stable Mode Chores
+#### Step 7C: Generate and Propose Stable Mode Chores
 
 **⚡ ASYNC BOUNDARY - Must wait for user confirmation**
 
@@ -628,7 +648,7 @@ Sound good? I'll create these chores once you confirm.
 
 **⚡ WAIT for user confirmation or adjustments.**
 
-#### Step 7C: Create Chores and Complete Transition
+#### Step 7D: Create Chores and Complete Transition
 
 **After user confirms, execute autonomously:**
 
@@ -665,7 +685,7 @@ jettypod work merge --release-lock
 jettypod work set-mode <feature-id> stable
 ```
 
-#### Step 7D: Invoke Stable Mode Skill
+#### Step 7E: Invoke Stable Mode Skill
 
 **🛑 CRITICAL HANDOFF - You MUST invoke stable-mode using the Skill tool.**
 
@@ -708,6 +728,7 @@ The stable-mode skill will:
 
 Before ending speed-mode skill, ensure:
 - [ ] All speed mode chores complete (GREEN on all success scenarios)
+- [ ] **Integration scenario passes** (feature is reachable, not an "island")
 - [ ] Stable mode BDD scenarios generated and committed
 - [ ] Step definitions created for stable scenarios
 - [ ] Stable mode chores created

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

@@ -57,7 +57,8 @@ When this skill is activated, you are helping implement a stable mode chore to a
 **Stable Mode Goal:** Transform speed mode's "make it work" implementation into robust, reliable code with comprehensive error handling and validation.
 
 **CRITICAL DISTINCTION:**
-- **Speed mode implemented ALL functionality** - every feature/function is already working (all success scenarios)
+- **Speed mode implemented ALL functionality** - every feature/function is already working (integration + all success scenarios)
+- **Speed mode verified integration** - the feature is reachable by users (Integration Scenario passed)
 - **Stable mode adds COMPLETE robustness** - error handling, validation, and edge cases
 
 **Key Principles:**
@@ -612,6 +613,7 @@ The production-mode skill will:
 
 Before ending stable-mode skill, ensure:
 - [ ] All stable mode chores complete (GREEN on all error/edge case scenarios)
+- [ ] Integration scenario still passes (feature remains reachable after error handling added)
 - [ ] Final chore merged to main
 - [ ] Project state checked (internal vs external)
 - [ ] **INTERNAL:** Feature marked as done