evizi-kit 1.0.0

package/kits/shared/skills/self-review/references/frontend.md

@@ -0,0 +1,103 @@
+# Frontend Code Review Checklist
+
+Use this checklist when reviewing Web Frontend code (React, Vue, Angular, Svelte, HTML/CSS).
+
+> **Severity guide**: Each item is tagged with a default severity. Adjust based on context — a missing error boundary in a settings page is a warning, but in a payment flow it's critical.
+> - ❌ = Critical (blocks PR)
+> - ⚠️ = Warning (should fix)
+> - 💡 = Suggestion (nice to have)
+
+## 🛡️ Security (review first)
+- ❌ **XSS Prevention**: Is `dangerouslySetInnerHTML` avoided or input sanitized? Unsanitized user content renders directly into the DOM.
+- ❌ **Sensitive Data Exposure**: Are tokens/passwords stored securely? (not in localStorage for auth tokens — use httpOnly cookies or secure session management)
+- ⚠️ **CSRF Protection**: Are CSRF tokens included in state-changing forms?
+- ⚠️ **Cookie Flags**: Are cookies set with `Secure`, `HttpOnly`, and `SameSite` flags?
+- ⚠️ **Third-Party Scripts**: Are CDN scripts verified with Subresource Integrity (SRI)?
+- 💡 **Content Security Policy**: Is CSP configured to limit script sources?
+
+## 🚨 Error Handling
+- ❌ **Error Boundaries**: Are error boundaries in place to catch component crashes? An uncaught error in a child component can take down the entire app.
+- ⚠️ **Fallback UI**: Is there graceful fallback for error states?
+- ⚠️ **Network Errors**: Are API failures handled with user-facing feedback and retry/fallback?
+- ⚠️ **Form Validation**: Are validation errors clearly displayed near the relevant fields?
+- 💡 **Error Messages**: Are messages user-friendly (not raw error objects or stack traces)?
+
+## 🧩 Component Architecture
+- ⚠️ **Component Size**: Are components too large (>200 lines)? Should they be split?
+- ⚠️ **Single Responsibility**: Does each component do one thing well?
+- ⚠️ **Prop Drilling**: Are props passed through many levels? (Consider context/state management)
+- 💡 **Reusability**: Are common patterns extracted to shared components?
+
+## 🗄️ State Management
+- ❌ **Effect Cleanups**: Do `useEffect` hooks clean up listeners/timers/subscriptions? Missing cleanups cause memory leaks and stale state bugs.
+- ⚠️ **State Location**: Is state at the right level (not too high, not too low)?
+- ⚠️ **Derived State**: Is redundant state avoided (computed from existing state)?
+- ⚠️ **State Updates**: Are state updates immutable?
+- 💡 **Global State**: Is global state (Redux/Zustand/Context) used only when needed?
+
+## ⚡ Performance & Rendering
+- ⚠️ **Re-renders**: Are components re-rendering unnecessarily? (Check `useCallback`/`useMemo` in React, `computed` in Vue)
+- ⚠️ **Bundle Size**: Are large libraries imported efficiently? (`import map from 'lodash/map'` vs `import _ from 'lodash'`)
+- ⚠️ **Race Conditions**: Are stale requests cancelled (AbortController) to prevent rendering outdated data?
+- 💡 **Image Optimization**: Are images lazy-loaded with explicit dimensions (prevent CLS)?
+- 💡 **List Virtualization**: Are long lists (>100 items) virtualized?
+- 💡 **Code Splitting**: Are routes and large components code-split?
+- 💡 **Memoization**: Are expensive computations memoized?
+
+## ⏳ Loading & Async States
+- ⚠️ **Loading Indicators**: Are loading states shown for async operations?
+- ⚠️ **Optimistic Updates**: Are UI updates optimistic where appropriate?
+- 💡 **Skeleton Screens**: Are skeleton loaders used instead of spinners for better UX?
+- 💡 **Suspense / Streaming**: Is React Suspense, Vue async components, or framework streaming used appropriately?
+
+## 📝 Forms & User Input
+- ⚠️ **Controlled Components**: Are form inputs properly controlled?
+- ⚠️ **Validation**: Is client-side validation implemented for required fields and formats?
+- ⚠️ **Submit Protection**: Are submit buttons disabled during API calls to prevent double submission?
+- 💡 **Debouncing**: Are expensive operations (search, API calls) debounced/throttled?
+- 💡 **Success Feedback**: Is user notified of successful actions?
+
+## 🔄 Data & API Integration
+- ⚠️ **Error States**: Are API errors caught and displayed to user?
+- ⚠️ **Request Cancellation**: Are pending requests cancelled on unmount?
+- 💡 **Caching**: Are API responses cached (React Query, SWR, Apollo) to avoid redundant requests?
+- 💡 **Retry Logic**: Are failed requests retried with backoff?
+
+## 📱 Responsiveness & CSS
+- ⚠️ **Mobile Support**: Does the layout work on small screens (320px+)?
+- ⚠️ **Design Tokens**: Are CSS variables/design tokens used instead of hardcoded values?
+- 💡 **Touch Targets**: Are interactive elements at least 44x44px?
+- 💡 **Animations**: Are animations performant (use `transform`/`opacity`, avoid layout thrashing)?
+- 💡 **Dark Mode**: Is dark mode support considered?
+
+## ♿ Accessibility (a11y)
+- ⚠️ **Semantic HTML**: Are proper elements used (`<button>`, `<nav>`, `<main>`, not `<div>` for everything)?
+- ⚠️ **Alt Text**: Do all images have meaningful `alt` attributes?
+- ⚠️ **Keyboard Navigation**: Are interactive elements reachable via Tab?
+- ⚠️ **Focus Indicators**: Are focus styles visible (not `outline: none` without replacement)?
+- 💡 **Color Contrast**: Does text meet WCAG contrast ratios (4.5:1 for normal text)?
+- 💡 **ARIA Labels**: Are ARIA labels used where native semantics are insufficient?
+- 💡 **Heading Hierarchy**: Are headings (h1-h6) used in logical order?
+
+## 🔒 Type Safety
+- ⚠️ **TypeScript**: Are types defined for props, state, and functions?
+- ⚠️ **Any Types**: Is `any` avoided? (use `unknown` or proper types)
+- ⚠️ **Null Checks**: Are nullable values properly handled?
+- 💡 **Type Inference**: Are types inferred where possible (avoid redundant annotations)?
+
+## 🧪 Testing & Quality
+- ⚠️ **Unit Tests**: Are components tested for key behaviors?
+- ⚠️ **Test IDs**: Are `data-testid` attributes added for E2E testing?
+- 💡 **Accessibility Tests**: Are a11y rules tested (jest-axe, testing-library)?
+- 💡 **Edge Cases**: Are loading/error states tested?
+
+## 🏗️ Code Quality
+- ⚠️ **Console Logs**: Are debug `console.log` statements removed?
+- ⚠️ **DRY Principle**: Is duplicated code refactored?
+- 💡 **Magic Numbers**: Are hardcoded values extracted to constants?
+- 💡 **Naming Conventions**: Are variables, functions, and components clearly named?
+
+## 🔍 SEO & Meta (if applicable)
+- 💡 **Meta Tags**: Are title, description, and Open Graph tags set?
+- 💡 **Semantic HTML**: Are heading tags used hierarchically?
+- 💡 **Canonical URLs**: Are canonical tags set for duplicate content?

package/kits/shared/skills/self-review/references/mobile.md

@@ -0,0 +1,108 @@
+# Mobile Code Review Checklist
+
+Use this checklist when reviewing iOS (Swift/SwiftUI) or Android (Kotlin/Jetpack Compose) code.
+
+> **Severity guide**: Each item is tagged with a default severity. Adjust based on context — a missing loading indicator on a debug screen is a suggestion, but on a checkout flow it's a warning.
+> - ❌ = Critical (blocks PR)
+> - ⚠️ = Warning (should fix)
+> - 💡 = Suggestion (nice to have)
+
+## 🔒 Security (review first)
+- ❌ **No Hardcoded Secrets**: Are API keys, tokens, and credentials stored in config/env — not committed in source code?
+- ❌ **Secure Storage**: Are sensitive credentials stored in Keychain (iOS) or Android Keystore — not SharedPreferences/UserDefaults?
+- ❌ **Deep Link Validation**: Are deep link parameters validated and sanitized to prevent injection attacks?
+- ⚠️ **Certificate Pinning**: Is SSL pinning implemented for sensitive API calls?
+- ⚠️ **Biometric Auth**: Is biometric authentication implemented with proper fallback (passcode)?
+- 💡 **Root/Jailbreak Detection**: Is rooted/jailbroken device detection implemented for sensitive flows?
+- 💡 **Screenshot Protection**: Is sensitive data hidden when app enters background (recent apps view)?
+- 💡 **Code Obfuscation**: Is ProGuard/R8 (Android) enabled for release builds?
+
+## 📱 Threading & Lifecycle
+- ❌ **Main Thread Safety**: Is heavy work (DB, network, computation, image processing) off the UI thread? Main-thread blocking causes ANRs (Android) and UI freezes (iOS).
+- ❌ **Lifecycle Cleanup**: Are observers, listeners, and subscriptions removed in `onDestroy`/`onDisappear`/`deinit`? Leaking these causes crashes and ghost updates.
+- ⚠️ **Memory Management**: Are strong reference cycles avoided in closures/listeners? (Use `[weak self]` in Swift, `WeakReference` in Kotlin)
+- ⚠️ **Configuration Changes**: Are configuration changes (rotation, dark mode, locale) handled without data loss?
+- ⚠️ **State Restoration**: Is state saved/restored correctly on process death?
+- 💡 **Permissions**: Are runtime permissions requested at appropriate times with clear explanation?
+
+## 🌐 Networking
+- ⚠️ **Timeout Configuration**: Are network requests configured with explicit timeouts?
+- ⚠️ **Error Handling**: Are network errors handled gracefully with user-friendly messages?
+- ⚠️ **Offline Mode**: Does the app handle "No Internet" states without crashing?
+- ⚠️ **Request Cancellation**: Are pending requests cancelled when leaving the screen?
+- 💡 **Retry Logic**: Are failed requests retried with exponential backoff?
+- 💡 **Response Validation**: Are API responses validated before use (null checks, type validation)?
+- 💡 **Network Reachability**: Is network status checked before making API calls?
+
+## 💾 Memory & Resources
+- ❌ **Memory Leaks**: Are retain cycles (iOS closures) and context leaks (Android activities in singletons) avoided?
+- ⚠️ **Image Handling**: Are bitmaps scaled/compressed before loading into memory? Full-resolution images in lists cause OOM.
+- ⚠️ **Image Caching**: Are images cached appropriately (Glide/Coil for Android, SDWebImage/Kingfisher for iOS)?
+- 💡 **Resource Files**: Are strings, colors, and dimensions in resource files (not hardcoded)?
+- 💡 **Memory Warnings**: Are memory warnings handled (iOS `didReceiveMemoryWarning`)?
+
+## ⚡ Performance
+- ⚠️ **List Recycling**: Are RecyclerView (Android) / LazyColumn (Compose) / List (SwiftUI) used for scrollable lists?
+- ⚠️ **Lazy Loading**: Are heavy resources loaded only when needed?
+- 💡 **App Launch Time**: Is cold start optimized? (Defer non-essential initialization)
+- 💡 **Smooth Animations**: Are animations smooth (avoid layout passes during animation)?
+- 💡 **Background Work**: Is WorkManager (Android) or BGTaskScheduler (iOS) used for background tasks?
+- 💡 **App Size**: Are unused resources and large assets optimized?
+
+## 🧭 Navigation & Architecture
+- ⚠️ **Navigation Patterns**: Is navigation consistent? (Navigation Component / Compose Navigation on Android, NavigationStack / Coordinator on iOS)
+- ⚠️ **Back Stack**: Is back navigation handled properly without stack corruption?
+- ⚠️ **Architecture Pattern**: Is MVVM / MVI followed consistently? Business logic should not live in Views.
+- 💡 **Dependency Injection**: Are dependencies injected (Hilt/Koin for Android, manual DI or Swinject for iOS)?
+- 💡 **Deep Linking**: Do deep links route to the correct screens?
+
+## 📱 UI/UX
+- ⚠️ **Safe Areas**: Does content respect notches, dynamic islands, and status bars?
+- ⚠️ **Loading States**: Are loading indicators shown for async operations?
+- ⚠️ **Error States**: Are error messages user-friendly with retry options?
+- ⚠️ **Keyboard Handling**: Does the keyboard not cover input fields? (Insets, scroll adjustment)
+- 💡 **Touch Feedback**: Do interactive elements show visual feedback when pressed?
+- 💡 **Empty States**: Are empty states designed with helpful messages?
+- 💡 **Pull to Refresh**: Is pull-to-refresh implemented where appropriate?
+
+## ♿ Accessibility
+- ⚠️ **Screen Reader**: Is content accessible to VoiceOver (iOS) / TalkBack (Android)?
+- ⚠️ **Content Descriptions**: Do images/icons have content descriptions?
+- ⚠️ **Touch Targets**: Are touch targets at least 44x44 points?
+- 💡 **Font Scaling**: Does UI support dynamic font sizes?
+- 💡 **Color Contrast**: Does text meet WCAG contrast requirements?
+
+## 🌍 Localization
+- ⚠️ **Hardcoded Strings**: Are all user-facing strings in resource files (Localizable.strings / strings.xml)?
+- 💡 **RTL Support**: Does layout support right-to-left languages?
+- 💡 **Date/Number Formatting**: Are dates/numbers formatted for locale?
+- 💡 **Plurals**: Are plural strings handled correctly?
+
+## 💾 Data Persistence
+- ⚠️ **Database**: Is Room (Android) or Core Data / SwiftData (iOS) used correctly?
+- ⚠️ **Migrations**: Are database migrations handled safely without data loss?
+- 💡 **Cache Management**: Is cached data invalidated when stale?
+- 💡 **Preferences**: Are SharedPreferences/UserDefaults used only for simple key-value data?
+
+## 🧪 Testing
+- ⚠️ **Unit Tests**: Are business logic and ViewModels tested?
+- 💡 **UI Tests**: Are critical user flows tested (Espresso/Compose Testing / XCUITest)?
+- 💡 **Mock Data**: Are network calls mocked for testing?
+- 💡 **Edge Cases**: Are error states and edge cases tested?
+
+## 📊 Analytics & Monitoring
+- ⚠️ **Crash Reporting**: Is crash reporting configured (Firebase Crashlytics / Sentry)?
+- 💡 **Analytics Events**: Are key user actions tracked?
+- 💡 **Performance Monitoring**: Is app performance monitored (launch time, screen load)?
+- 💡 **ANR Detection**: Are ANRs monitored (Android)?
+
+## 🏗️ Code Quality
+- ⚠️ **Naming Conventions**: Are classes, functions, and variables clearly named per platform conventions?
+- ⚠️ **DRY Principle**: Is duplicated code refactored?
+- ⚠️ **Deprecated APIs**: Are deprecated APIs replaced with modern alternatives?
+- 💡 **Magic Numbers**: Are hardcoded values extracted to constants?
+
+## 🛠️ Build & CI/CD
+- ⚠️ **Signing**: Are signing configs secure (not committed to repo)?
+- 💡 **Build Variants**: Are debug/release builds configured properly?
+- 💡 **Version Code/Number**: Are version codes incremented?

package/kits/shared/skills/self-review/templates/issues.template.md

@@ -0,0 +1,72 @@
+# Self Review Report
+
+**Branch**: `[CURRENT_BRANCH]` → `[TARGET_BRANCH]`  
+**Reviewed**: [DATE]  
+**Tech Stack**: [DETECTED_STACKS]
+
+## 🎯 Verdict: [VERDICT_STATUS]
+
+[VERDICT_MESSAGE]
+
+> [DIVERGENCE_WARNING — include only if target branch has new commits since this branch diverged]
+> ⚠️ Target branch has X new commit(s) since this branch diverged. This review covers your branch's changes only and cannot detect conflicts with new code on [TARGET_BRANCH]. Consider rebasing before PR.
+
+> [PRIORITIZED_REVIEW_NOTE — include only if diff exceeded 30 files or 2000 lines]
+> ℹ️ Large diff (X files / Y lines). Review was prioritized: security-sensitive and high-change files reviewed in depth. Generated/config/lock files received lighter review.
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Files Reviewed | [FILES_COUNT] |
+| Critical Issues | [CRITICAL_COUNT] ❌ |
+| Warnings | [WARNING_COUNT] ⚠️ |
+| Suggestions | [SUGGESTION_COUNT] 💡 |
+| Guidelines Loaded | [GUIDELINES_LIST or "Domain checklists only"] |
+
+## Files Reviewed
+
+| File | Status | Lines Changed | Issues |
+|------|--------|---------------|--------|
+| `[FILE_PATH]` | [STATUS_ICON] | +[ADDED] / -[REMOVED] | [ISSUE_COUNT] |
+
+## ❌ Critical Issues (Must Fix)
+
+> Bugs, security vulnerabilities, breaking changes, data loss risks.
+
+| # | File | Line | Category | Issue | Recommendation |
+|---|------|------|----------|-------|----------------|
+| [ISSUE_ID] | `[FILE_PATH]` | [LINE_NUMBER] | [CATEGORY] | [ISSUE_DESCRIPTION] | [FIX_RECOMMENDATION] |
+
+_No critical issues found._ <!-- Remove this line if issues exist -->
+
+## ⚠️ Warnings (Should Fix)
+
+> Code quality, readability, maintainability, missing error handling.
+
+| # | File | Line | Category | Issue | Recommendation |
+|---|------|------|----------|-------|----------------|
+| [ISSUE_ID] | `[FILE_PATH]` | [LINE_NUMBER] | [CATEGORY] | [ISSUE_DESCRIPTION] | [FIX_RECOMMENDATION] |
+
+_No warnings found._ <!-- Remove this line if issues exist -->
+
+## 💡 Suggestions (Nice to Have)
+
+> Patterns, optimizations, naming improvements.
+
+| # | File | Line | Category | Issue | Recommendation |
+|---|------|------|----------|-------|----------------|
+| [ISSUE_ID] | `[FILE_PATH]` | [LINE_NUMBER] | [CATEGORY] | [ISSUE_DESCRIPTION] | [FIX_RECOMMENDATION] |
+
+_No suggestions found._ <!-- Remove this line if issues exist -->
+
+<!-- Include only if project-specific guidelines were loaded -->
+## 📐 Project Convention Issues
+
+> Violations of project blueprint, instructions, or best practices. Category shows which document the rule comes from.
+
+| # | File | Line | Source | Issue | Recommendation |
+|---|------|------|--------|-------|----------------|
+| [ISSUE_ID] | `[FILE_PATH]` | [LINE_NUMBER] | [Blueprint / Instructions / Best Practices] | [ISSUE_DESCRIPTION] | [FIX_RECOMMENDATION] |
+
+_No project convention issues found._ <!-- Remove this line if issues exist -->

package/kits/shared/skills/update-feature-document/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: update-feature-document
+description: Update feature documentation after successfully implementing a ticket. Updates feature.md (behavior specifications) and delta.yaml (ticket history log) in .documents-design/features/[PARENT_FEATURE]/[CHILD_FEATURE]/. ALWAYS use this skill when a ticket is done and the feature docs need to reflect the work — even if the user doesn't say "feature document" explicitly. Triggers on requests like "update feature document for ticket TKT-001", "log ticket ABC-123 to feature", "update feature after implementing fe-2026", "record ticket completion for feature", "sync docs after finishing ticket X", "document what was done for ticket Y", "update docs for the completed ticket", "log the work from ticket Z", or any mention of recording/logging a finished ticket into feature documentation.
+---
+
+# Update Feature Document
+
+Feature documentation is the living record of what a feature does and how it got there. `feature.md` captures the behavioral specification (what users can do), while `delta.yaml` tracks the ticket-by-ticket history of how the feature was built. Keeping these in sync after each ticket matters because they serve as the source of truth for anyone — human or AI — who needs to understand the feature's current state, what's already covered, and what's left to build.
+
+This skill walks through reading the ticket artifacts, deciding what changed at the behavior level, and updating both files accordingly.
+
+## Input
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `TICKET_ID` | string | Yes | The ticket identifier (e.g., AUTO-2611, MM-19) |
+
+If `TICKET_ID` is not provided, ask the user before proceeding.
+
+## Workflow
+
+### Step 1: Locate the Ticket
+
+Look for the ticket directory at `.tickets/{TICKET_ID}/`.
+
+If not found, inform the user and stop — without ticket artifacts there is nothing to extract:
+
+```
+Ticket directory not found for {TICKET_ID}. Check that .tickets/{TICKET_ID}/ exists.
+```
+
+### Step 2: Gather Ticket Context
+
+Read available ticket artifacts. Not every ticket has all of these — read whichever exist, in this priority order (higher-priority files tend to have more concise, already-synthesized information):
+
+1. `lessons-learned.md` — summary, outcome, issues fixed
+2. `issues-resolution-report.md` — run status, files modified
+3. `ticket-playbook.md` — implementation tasks
+4. `ticket-design.md` — test steps and behaviors covered
+5. `test-cases.md` — BDD scenarios and behavior IDs
+
+#### 2a — Identify the Feature Path
+
+The feature path (`PARENT_FEATURE` / `CHILD_FEATURE`) tells you where to find the feature documents under `.documents-design/features/`. Try these sources in order until you get a match:
+
+1. **`test-cases.md`** — look for the `Feature:` line (format: `Feature: {PARENT_FEATURE} - {CHILD_FEATURE}`)
+2. **`ticket-design.md`** — look for a feature reference in the header or "Feature" field
+3. **`ticket-playbook.md`** — may reference the feature path in the task descriptions
+
+If none of these yield a parseable feature path, ask the user to provide it.
+
+#### 2b — Extract Ticket Data
+
+Pull these fields from whichever artifacts are available:
+
+| Field | Where to look | Fallback |
+|-------|---------------|----------|
+| **Summary** (1-2 sentences) | `lessons-learned.md` summary, or `ticket-design.md` overview | Compose from available context |
+| **Ticket type** (`automation` / `feature` / `bugfix` / `refactor`) | Infer from content — automation tickets create test specs, feature tickets add product capabilities | `automation` if unclear |
+| **Behaviors covered** (IDs like COM-1, COM-2) | `test-cases.md` scenario tags, `ticket-design.md` behavior list | List scenario names if no IDs exist |
+| **Behaviors affected** (indirectly impacted IDs) | `lessons-learned.md` side effects, `issues-resolution-report.md` modified files touching other behaviors | `[]` if none apparent |
+| **Files created** | `issues-resolution-report.md`, `lessons-learned.md` | `[]` |
+| **Files modified** | `issues-resolution-report.md`, `lessons-learned.md` | `[]` |
+| **Test result** (`passed` / `failed` / `skipped`) | `issues-resolution-report.md` run status, `lessons-learned.md` outcome | `unknown` |
+| **Notes** | Anything notable — workarounds, flaky selectors, environment quirks | `""` |
+
+### Step 3: Update feature.md
+
+Read the current feature file:
+
+```
+.documents-design/features/{PARENT_FEATURE}/{CHILD_FEATURE}/feature.md
+```
+
+**If the file doesn't exist:** This is the first time the feature is being documented. Create the directory `.documents-design/features/{PARENT_FEATURE}/{CHILD_FEATURE}/` if it doesn't exist, then create `feature.md` using the structure from [templates/feature.template.md](templates/feature.template.md), filling in the user story and behaviors from the ticket data. Let the user know you created a new feature.md rather than updating an existing one.
+
+**If the file exists:** Decide whether it needs changes. The key question is: *did this ticket reveal anything about the feature's behavior that the current document doesn't capture?*
+
+Update when you see concrete signals:
+- The ticket's BDD scenarios describe behaviors (Given/When/Then steps) not present in `feature.md`
+- Implementation revealed additional validation rules, error states, or edge cases that belong in the spec
+- Existing behavior descriptions are contradicted by what the ticket actually implemented (e.g., steps are in the wrong order, a condition was different from what was documented)
+
+Leave `feature.md` unchanged when:
+- The ticket purely automated existing behaviors that are already accurately described — adding automation coverage doesn't change the behavioral spec
+- The changes are code-level (refactored a helper, renamed a variable) with no visible impact on what users can do
+
+When updating, preserve the existing structure. Feature documents follow a User Story + Behavior Details pattern in BDD format. Add or modify only the sections affected by the ticket.
+
+### Step 4: Update delta.yaml
+
+Read the current delta file:
+
+```
+.documents-design/features/{PARENT_FEATURE}/{CHILD_FEATURE}/delta.yaml
+```
+
+#### If the file is empty or doesn't exist
+
+Create the directory `.documents-design/features/{PARENT_FEATURE}/{CHILD_FEATURE}/` if it doesn't already exist, then initialize the file with this structure:
+
+```yaml
+feature: "{CHILD_FEATURE}"
+parent: "{PARENT_FEATURE}"
+status: in-progress
+last_updated: "{TODAY_YYYY-MM-DD}"
+tickets:
+  - id: "{TICKET_ID}"
+    completed_at: "{TODAY_YYYY-MM-DD}"
+    type: "{TYPE}"
+    summary: "{SUMMARY}"
+    test_result: "{TEST_RESULT}"
+    behaviors_covered:
+      - "{BEHAVIOR_ID}"
+    behaviors_affected: []
+    files_created:
+      - "{FILE_PATH}"
+    files_modified: []
+    notes: ""
+```
+
+#### If the file already has content
+
+Append the new ticket entry to the `tickets` list. Never remove or reorder existing entries — this is an append-only log.
+
+#### Status Calculation
+
+The `status` field reflects how much of the feature's behavioral spec is covered by completed tickets. To calculate it, collect all `behaviors_covered` IDs across every ticket entry in delta.yaml, then compare against the behavior IDs defined in `feature.md`.
+
+| Status | Meaning | When to use |
+|--------|---------|-------------|
+| `draft` | Spec exists, no work done | `feature.md` has behaviors but delta.yaml has zero tickets |
+| `in-progress` | Partially built | Some behavior IDs from `feature.md` appear in ticket `behaviors_covered`, but not all |
+| `complete` | Fully covered | Every behavior ID in `feature.md` has at least one ticket claiming coverage |
+
+**Example:** If `feature.md` defines behaviors COM-1, COM-2, COM-3, and the tickets in delta.yaml collectively cover COM-1 and COM-2, the status is `in-progress`. Once a ticket claiming COM-3 is added, it becomes `complete`.
+
+If `feature.md` doesn't use explicit behavior IDs (some features may not), compare at the scenario level — match ticket test scenarios against documented behaviors by name/description.
+
+Always set `last_updated` to today's date.
+
+### Step 5: Summary
+
+Display the result:
+
+```
+Feature document updated for ticket {TICKET_ID}.
+
+Feature: {PARENT_FEATURE}/{CHILD_FEATURE}
+feature.md: {Created / Updated / No changes needed}
+delta.yaml: Ticket {TICKET_ID} logged
+
+Behaviors covered: {list}
+Test result: {passed/failed/skipped/unknown}
+Feature status: {draft/in-progress/complete}
+```

package/kits/shared/skills/update-feature-document/templates/delta.template.yaml

@@ -0,0 +1,58 @@
+# delta.yaml Structure
+
+Use this template to initialize or extend `delta.yaml` in a feature directory.
+
+## Empty Feature (initialization)
+
+```yaml
+feature: "{CHILD_FEATURE}"
+parent: "{PARENT_FEATURE}"
+status: draft # draft | in-progress | complete
+last_updated: "{YYYY-MM-DD}"
+tickets: []
+```
+
+## After Adding a Ticket
+
+```yaml
+feature: "companies"
+parent: "companies"
+status: in-progress
+last_updated: "2026-02-26"
+tickets:
+  - id: "auto-2611"
+    completed_at: "2026-02-26"
+    type: automation # automation | feature | bugfix | refactor
+    summary: "Implemented search, filter, and sort for companies list"
+    test_result: passed # passed | failed | skipped
+    behaviors_covered:
+      - "COM-1"
+      - "COM-2"
+    behaviors_affected: []
+    files_created:
+      - "tests/companies/companies-search.spec.ts"
+      - "pages/companies/companies-list.page.ts"
+    files_modified:
+      - "data/companies/test-data.ts"
+    notes: "" # optional additional context
+```
+
+## Field Reference
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `feature` | string | Child feature name (directory name) |
+| `parent` | string | Parent feature name (parent directory name) |
+| `status` | enum | `draft` = no tickets done, `in-progress` = partial coverage, `complete` = all behaviors covered |
+| `last_updated` | date | ISO date of last update |
+| `tickets` | list | Chronological log of all completed tickets |
+| `tickets[].id` | string | Ticket identifier |
+| `tickets[].completed_at` | date | ISO date when ticket was completed |
+| `tickets[].type` | enum | `automation` \| `feature` \| `bugfix` \| `refactor` |
+| `tickets[].summary` | string | 1-2 sentence description of what was done |
+| `tickets[].test_result` | enum | `passed` \| `failed` \| `skipped` |
+| `tickets[].behaviors_covered` | list | Behavior IDs directly implemented |
+| `tickets[].behaviors_affected` | list | Behavior IDs indirectly impacted |
+| `tickets[].files_created` | list | Paths of new files created |
+| `tickets[].files_modified` | list | Paths of modified files |
+| `tickets[].notes` | string | Optional additional context |

package/kits/shared/skills/update-feature-document/templates/feature.template.md

@@ -0,0 +1,25 @@
+# Feature: {CHILD_FEATURE}
+
+> **Parent feature:** {PARENT_FEATURE}
+
+## User Story
+
+As a [role],
+I want to [action],
+so that [benefit].
+
+## Behavior Details
+
+### {BEHAVIOR_ID_1}: {Behavior Title}
+
+**Given** [precondition]
+**And** [additional precondition if needed]
+**When** [action taken]
+**Then** [expected outcome]
+**And** [additional expected outcome if needed]
+
+### {BEHAVIOR_ID_2}: {Behavior Title}
+
+**Given** [precondition]
+**When** [action taken]
+**Then** [expected outcome]

package/kits/shared/skills/web-auto-assisted-fix-and-run/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: web-auto-assisted-fix-and-run
+description: Apply a user-provided hint to a failing test and run it once. Receives the failure summary and user hint from the master agent, applies the guidance, and runs the test. Appends the result to the existing issues-resolution-report.md and emits a structured ASSISTED-RUN RESULT block. The master agent decides how many times to invoke this skill and tracks attempt counts. Use when the autonomous fix attempt has been exhausted and user expertise is needed. Triggers when invoked by the master agent after a FIX-AND-RUN RESULT: FAILED or ASSISTED-RUN RESULT: FAILED block. Also use when someone says "apply the user's hint to the failing test", "user-assisted fix for ticket X", "run the test with this hint", "try the user's suggestion for the failing test", or any variation of applying external guidance to a test failure — even if they don't explicitly say "assisted fix and run".
+---
+
+# Web Automation User-Assisted Fix
+
+Apply a user-provided hint to a failing test, run it once, and return a structured result. The master agent handles user interaction, attempt counting, retry logic, and pipeline routing — this skill focuses entirely on applying the hint, running the test, and reporting the outcome.
+
+## Why This Skill Exists
+
+When `web-auto-fix-and-run-test` runs and the test fails, the autonomous pipeline has exhausted its ability to self-correct. The runtime error often involves something the model can't resolve alone — a selector that changed in the live app, an API contract mismatch, a test environment quirk, or a timing issue only a human recognizes. The user provides a hint rooted in their knowledge of the application, and this skill bridges that human insight into the codebase. Getting this right saves the user from having to make the code change themselves.
+
+## Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `TICKET_ID` | string | Yes | The ticket identifier (e.g., TKT-001, ABC-123) |
+| `FAILURE_SUMMARY` | block | Yes | The structured `FIX-AND-RUN RESULT: FAILED` or `ASSISTED-RUN RESULT: FAILED` block from the previous attempt |
+| `USER_HINT` | string | Yes | The hint or fix guidance provided by the user, collected by the master agent before invoking |
+
+**If `TICKET_ID` is not provided:** Ask the user for it before proceeding.
+**If `FAILURE_SUMMARY` is missing:** Read `.tickets/{TICKET_ID}/issues-resolution-report.md` to reconstruct the last known error.
+**If `USER_HINT` is missing:** Stop and report the missing input to the master agent. The master agent is responsible for collecting the hint from the user before invoking this skill — prompting the user directly would break the pipeline's communication flow.
+
+## Workflow
+
+### Step 1: Build Full Context
+
+Before touching any code, build a complete picture of what happened, what was already tried, and what the user is suggesting. Skipping this leads to repeating failed fixes or misinterpreting the hint.
+
+**1.1 — Parse the failure summary**
+
+Extract from the `FAILURE_SUMMARY` block:
+- **Error Type** — determines which resolution reference to consult
+- **Location** (file:line) — where to focus the fix
+- **Message** — the exact error text
+- **Issues Fixed Before Run** — what was already changed
+- **Likely Cause** (if present) — the previous agent's diagnosis
+
+**1.2 — Read the fix history**
+
+Read `.tickets/{TICKET_ID}/issues-resolution-report.md` and look for:
+- **What fixes were already applied** — avoid re-applying the same change or a variation that already failed
+- **The progression of errors** — did the error type change between attempts? A changing error type means the previous fix had partial effect; a repeating error means the fix didn't address the root cause
+- **Patterns across attempts** — if multiple attempts targeted the same area, the root cause might be elsewhere
+
+**1.3 — Read implementation context**
+
+- Read `.tickets/{TICKET_ID}/ticket-playbook.md` to understand what the code implements, its dependencies, and the expected behavior
+- Read `.tickets/{TICKET_ID}/issues.md` to get the **run command** from the "Notes for Fix-and-Run" section
+
+### Step 2: Interpret the User Hint
+
+The user hint is the most valuable input in this skill. Invest time understanding it before writing any code. Users express hints in different ways:
+
+| Hint Pattern | What They Mean | How to Act |
+|-------------|----------------|------------|
+| Specific code change ("change the selector to `#submit-btn`") | Direct instruction — apply it literally | Apply the exact change, then verify it's syntactically valid |
+| Diagnosis without a fix ("the login modal takes 3 seconds to load") | They know the root cause but need you to translate it into code | Use the diagnosis to locate the right part of the code and apply an appropriate fix (e.g., add a wait, increase timeout) |
+| Context that wasn't available ("the API endpoint changed to `/v2/users`") | New information the autonomous run didn't have | Update the relevant code with the new value and check for other references to the old value |
+| Broad direction ("try a different selector approach") | They want you to choose a different strategy | Consult `references/resolve-selector.md` or `references/resolve-api-error.md` and try the next path in the cascade |
+| Combination ("the button text changed to 'Sign In' and the form needs 2s to load") | Multiple changes needed | Apply all changes together before running, since each alone might not be sufficient |
+
+If the hint conflicts with what the failure summary suggests, trust the user — they have context you don't (access to the running application, knowledge of recent changes, understanding of business logic).
+
+### Step 3: Apply the Fix
+
+**3.1 — Make the code change**
+
+- For selector errors (`LocatorError`, element `TimeoutError`): follow `references/resolve-selector.md`. Guessing selectors leads to cascading failures — one wrong selector triggers a different error, which triggers another guess, and the test drifts further from working
+- For API errors (wrong endpoint, wrong payload, 4xx/5xx HTTP status): follow `references/resolve-api-error.md`. API contracts are exact — a single wrong field name or path segment causes a failure that looks identical to many other issues
+- For all other errors: apply the hint directly, using the failure location and message as your guide
+
+**3.2 — Verify before running**
+
+- Check for syntax errors in the modified file(s)
+- If the fix touches an import, export, or method signature, verify that callers and importers are still compatible
+- If a fix introduces a new syntax or lint error, revert it and try an alternative interpretation of the hint rather than stacking fixes on top of a broken change
+
+### Step 4: Run the Test
+
+- Run the test **exactly once** — do not retry on failure. The master agent owns the retry decision.
+- Use the run command from the "Notes for Fix-and-Run" section of `issues.md`
+- Capture full output (stdout and stderr)
+- **Success** → proceed to Step 5
+- **Failure** → proceed to Step 6
+
+### Step 5: Success — Append to Resolution Report
+
+Append the **User-Assisted Success section** to the existing `.tickets/{TICKET_ID}/issues-resolution-report.md` using the template from [templates/issues-resolution-report-append.template.md](templates/issues-resolution-report-append.template.md).
+
+Emit the result block for the master agent:
+
+```
+ASSISTED-RUN RESULT: PASSED
+Ticket: {TICKET_ID}
+Report updated: .tickets/{TICKET_ID}/issues-resolution-report.md
+```
+
+### Step 6: Failure — Append to Resolution Report
+
+Append the **User-Assisted Failure section** to the existing `.tickets/{TICKET_ID}/issues-resolution-report.md` using the template from [templates/issues-resolution-report-append.template.md](templates/issues-resolution-report-append.template.md).
+
+Emit the result block for the master agent:
+
+```
+ASSISTED-RUN RESULT: FAILED
+Ticket: {TICKET_ID}
+Error Type: {error type}
+Location: {file:line}
+Message: {error message}
+Report updated: .tickets/{TICKET_ID}/issues-resolution-report.md
+```
+
+## Guidelines
+
+These aren't arbitrary rules — each exists because of how this skill fits into the pipeline.
+
+- **One attempt per invocation.** The master agent orchestrates the retry loop and decides how many times to invoke this skill. Running multiple attempts here would bypass the master agent's control over the retry flow.
+
+- **Don't prompt the user directly.** The master agent presents errors and collects hints from the user in a structured way. If this skill also started asking questions, the user would get duplicate prompts from different agents, which is confusing and breaks the pipeline's communication model.
+
+- **Append to the resolution report, never overwrite it.** The report is a running log of everything that's been tried. Overwriting it loses the history that the next attempt (or the user) needs to understand what already failed and why.
+
+- **Emit the `ASSISTED-RUN RESULT:` block on every outcome.** The master agent parses this block to decide what happens next — PASSED routes to push-code, FAILED routes to the next user-assisted attempt or pipeline stop. Without it, the pipeline stalls waiting for a signal that never comes.
+
+- **Don't modify `issues.md`.** It's the original review output from `web-auto-self-reviewer` and serves as the source of truth for what was initially wrong. Fixes go into the implementation files; the resolution report tracks what changes were made.
+
+- **Use the run command from `issues.md`.** The "Notes for Fix-and-Run" section contains the exact command that `web-auto-fix-and-run-test` used. Using a different command could produce different results for reasons unrelated to the fix, making it impossible to tell if the hint actually worked.