flight-rules 0.15.3 → 0.15.4

package/dist/commands/adapter.d.ts

@@ -5,6 +5,20 @@ export declare function copyCommandsWithConflictHandling(sourceDir: string, dest
     copied: string[];
     skipped: string[];
 }>;
+/**
+ * Copy skill files to a destination directory with conflict handling
+ */
+export declare function copySkillsWithConflictHandling(sourceDir: string, destDir: string, skipPrompts?: boolean): Promise<{
+    copied: string[];
+    skipped: string[];
+}>;
+/**
+ * Setup skills for a given adapter directory
+ */
+export declare function setupSkills(cwd: string, sourceSkillsDir: string, adapterSkillsDir: string, skipPrompts?: boolean): Promise<{
+    copied: string[];
+    skipped: string[];
+}>;
 /**
  * Setup Cursor-specific directories and commands
  */

package/dist/commands/adapter.js

@@ -140,6 +140,68 @@ async function promptForConflict(filename, showBatchOptions) {
     }
     return action;
 }
+/**
+ * Copy skill files to a destination directory with conflict handling
+ */
+export async function copySkillsWithConflictHandling(sourceDir, destDir, skipPrompts = false) {
+    const copied = [];
+    const skipped = [];
+    if (!existsSync(sourceDir)) {
+        return { copied, skipped };
+    }
+    const files = readdirSync(sourceDir).filter(f => f.endsWith('.md'));
+    let batchAction = null;
+    for (const file of files) {
+        const srcPath = join(sourceDir, file);
+        const destPath = join(destDir, file);
+        if (existsSync(destPath)) {
+            if (skipPrompts) {
+                cpSync(srcPath, destPath);
+                copied.push(file);
+                continue;
+            }
+            if (batchAction === 'replace_all') {
+                cpSync(srcPath, destPath);
+                copied.push(file);
+                continue;
+            }
+            else if (batchAction === 'skip_all') {
+                skipped.push(file);
+                continue;
+            }
+            const action = await promptForConflict(file, files.length > 1);
+            if (action === 'replace_all') {
+                batchAction = 'replace_all';
+                cpSync(srcPath, destPath);
+                copied.push(file);
+            }
+            else if (action === 'skip_all') {
+                batchAction = 'skip_all';
+                skipped.push(file);
+            }
+            else if (action === 'replace') {
+                cpSync(srcPath, destPath);
+                copied.push(file);
+            }
+            else {
+                skipped.push(file);
+            }
+        }
+        else {
+            cpSync(srcPath, destPath);
+            copied.push(file);
+        }
+    }
+    return { copied, skipped };
+}
+/**
+ * Setup skills for a given adapter directory
+ */
+export async function setupSkills(cwd, sourceSkillsDir, adapterSkillsDir, skipPrompts = false) {
+    ensureDir(join(cwd, adapterSkillsDir.split('/')[0])); // e.g., .claude
+    ensureDir(join(cwd, adapterSkillsDir));
+    return copySkillsWithConflictHandling(sourceSkillsDir, join(cwd, adapterSkillsDir), skipPrompts);
+}
 /**
  * Setup Cursor-specific directories and commands
  */
@@ -240,8 +302,10 @@ export async function adapter(args) {
 }
 export async function generateAdapters(adapterNames, sourceCommandsDir, interactive = true) {
     const cwd = process.cwd();
+    const flightRulesDir = getFlightRulesDir(cwd);
     // Default to .flight-rules/commands if no source specified
-    const commandsDir = sourceCommandsDir ?? join(getFlightRulesDir(cwd), 'commands');
+    const commandsDir = sourceCommandsDir ?? join(flightRulesDir, 'commands');
+    const skillsDir = join(flightRulesDir, 'skills');
     for (const name of adapterNames) {
         const config = ADAPTERS[name];
         if (!config)
@@ -278,7 +342,7 @@ export async function generateAdapters(adapterNames, sourceCommandsDir, interact
             p.log.success(`Created ${pc.cyan(config.filename)} for ${config.name}`);
             adapterFileWritten = true;
         }
-        // For Cursor, also set up .cursor/commands/
+        // For Cursor, also set up .cursor/commands/ and .cursor/skills/
         if (name === 'cursor') {
             const skipPrompts = !interactive;
             const commandsDirExists = isCursorAdapterInstalled(cwd);
@@ -290,8 +354,18 @@ export async function generateAdapters(adapterNames, sourceCommandsDir, interact
             if (result.skipped.length > 0) {
                 p.log.info(`Skipped ${result.skipped.length} existing command(s) in .cursor/commands/`);
             }
+            // Copy skills
+            if (existsSync(skillsDir)) {
+                const skillResult = await setupSkills(cwd, skillsDir, '.cursor/skills', skipPrompts);
+                if (skillResult.copied.length > 0) {
+                    p.log.success(`${commandsDirExists ? 'Updated' : 'Created'} ${pc.cyan('.cursor/skills/')} with ${skillResult.copied.length} skill(s)`);
+                }
+                if (skillResult.skipped.length > 0) {
+                    p.log.info(`Skipped ${skillResult.skipped.length} existing skill(s) in .cursor/skills/`);
+                }
+            }
         }
-        // For Claude, also set up .claude/commands/
+        // For Claude, also set up .claude/commands/ and .claude/skills/
         if (name === 'claude') {
             const skipPrompts = !interactive;
             const commandsDirExists = isClaudeAdapterInstalled(cwd);
@@ -303,6 +377,16 @@ export async function generateAdapters(adapterNames, sourceCommandsDir, interact
             if (result.skipped.length > 0) {
                 p.log.info(`Skipped ${result.skipped.length} existing command(s) in .claude/commands/`);
             }
+            // Copy skills
+            if (existsSync(skillsDir)) {
+                const skillResult = await setupSkills(cwd, skillsDir, '.claude/skills', skipPrompts);
+                if (skillResult.copied.length > 0) {
+                    p.log.success(`${commandsDirExists ? 'Updated' : 'Created'} ${pc.cyan('.claude/skills/')} with ${skillResult.copied.length} skill(s)`);
+                }
+                if (skillResult.skipped.length > 0) {
+                    p.log.info(`Skipped ${skillResult.skipped.length} existing skill(s) in .claude/skills/`);
+                }
+            }
         }
     }
 }

package/dist/commands/upgrade.js

@@ -4,7 +4,7 @@ import { existsSync, cpSync } from 'fs';
 import { join } from 'path';
 import { isFlightRulesInstalled, fetchPayloadFromGitHub, copyFrameworkFilesFrom, ensureDir, getInstalledVersion, writeManifest, getCliVersion } from '../utils/files.js';
 import { isInteractive } from '../utils/interactive.js';
-import { isCursorAdapterInstalled, isClaudeAdapterInstalled, setupCursorCommands, setupClaudeCommands, } from './adapter.js';
+import { isCursorAdapterInstalled, isClaudeAdapterInstalled, setupCursorCommands, setupClaudeCommands, setupSkills, } from './adapter.js';
 const DOC_FILES = [
     { src: 'prd.md', dest: 'prd.md' },
     { src: 'progress.md', dest: 'progress.md' },
@@ -148,21 +148,34 @@ export async function upgrade(version) {
         spinner.start('Upgrading adapters...');
         try {
             const sourceCommandsDir = join(fetched.payloadPath, 'commands');
-            // Upgrade Cursor commands if installed
+            const sourceSkillsDir = join(fetched.payloadPath, 'skills');
+            // Upgrade Cursor commands and skills if installed
             if (cursorAdapterInstalled) {
                 const result = await setupCursorCommands(cwd, sourceCommandsDir, true); // skipPrompts = true for upgrade
                 if (result.copied.length > 0) {
                     p.log.success(`Updated ${result.copied.length} command(s) in .cursor/commands/`);
                 }
+                if (existsSync(sourceSkillsDir)) {
+                    const skillResult = await setupSkills(cwd, sourceSkillsDir, '.cursor/skills', true);
+                    if (skillResult.copied.length > 0) {
+                        p.log.success(`Updated ${skillResult.copied.length} skill(s) in .cursor/skills/`);
+                    }
+                }
             }
-            // Upgrade Claude commands if installed, or create them if CLAUDE.md exists but .claude/commands/ doesn't
-            // (handles upgrade from pre-0.5.4 where Claude didn't have native commands)
+            // Upgrade Claude commands and skills if installed
             if (claudeAdapterInstalled || claudeMdExists) {
                 const result = await setupClaudeCommands(cwd, sourceCommandsDir, true); // skipPrompts = true for upgrade
                 if (result.copied.length > 0) {
                     const action = claudeAdapterInstalled ? 'Updated' : 'Created';
                     p.log.success(`${action} ${result.copied.length} command(s) in .claude/commands/`);
                 }
+                if (existsSync(sourceSkillsDir)) {
+                    const skillResult = await setupSkills(cwd, sourceSkillsDir, '.claude/skills', true);
+                    if (skillResult.copied.length > 0) {
+                        const action = claudeAdapterInstalled ? 'Updated' : 'Created';
+                        p.log.success(`${action} ${skillResult.copied.length} skill(s) in .claude/skills/`);
+                    }
+                }
             }
             // Regenerate adapter files
             const adaptersToRegenerate = [];

package/dist/utils/files.js

@@ -67,7 +67,8 @@ export function copyFrameworkFiles(targetDir) {
         'AGENTS.md',
         'doc-templates',
         'commands',
-        'prompts'
+        'prompts',
+        'skills'
     ];
     for (const item of frameworkItems) {
         const srcItem = join(payloadPath, item);
@@ -175,7 +176,8 @@ export function copyFrameworkFilesFrom(sourcePayloadPath, targetDir) {
         'AGENTS.md',
         'doc-templates',
         'commands',
-        'prompts'
+        'prompts',
+        'skills'
     ];
     for (const item of frameworkItems) {
         const srcItem = join(sourcePayloadPath, item);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flight-rules",
-  "version": "0.15.3",
+  "version": "0.15.4",
   "description": "An opinionated framework for AI-assisted software development",
   "type": "module",
   "main": "dist/index.js",

package/payload/AGENTS.md

@@ -1,6 +1,6 @@
 # Flight Rules – Agent Guidelines
 
-flight_rules_version: 0.15.3
+flight_rules_version: 0.15.4
 
 This file defines how agents (Claude Code, Cursor, etc.) should work on software projects using the Flight Rules system.
 

package/payload/skills/web-prototype.md

@@ -0,0 +1,263 @@
+---
+name: web-prototype
+description: >
+  Create multiple distinct design variations of a web page as HTML/CSS/JS prototypes.
+  Use this skill whenever the user wants to create web prototypes, page mockups, design
+  variations, HTML page concepts, landing page options, or explore different visual
+  directions for a page. Also trigger when the user asks to "try different designs",
+  "show me options for a page", "create page variations", or anything involving generating
+  multiple visual alternatives of a web page. Even if the user just says "prototype this
+  page" or "mock up a landing page", this skill applies.
+---
+
+# Web Prototype Generator
+
+Create multiple visually distinct variations of a web page so the user can compare
+design directions side by side. Each variation is a standalone HTML file with inline
+CSS and JavaScript — no frameworks, no build steps, just open in a browser.
+
+## How it works
+
+1. Understand what the user wants the page to do and look like
+2. Check or create the project config (`.web-prototype.json`)
+3. Generate N variations (default 5), each as different as possible
+4. Inject a shared navigation bar so the user can flip between variants
+
+## Step 1: Understand the request
+
+Ask the user (if not already clear):
+- What is this page? (landing page, dashboard, portfolio, form, etc.)
+- What content should it include?
+- Any specific features? (see Feature Library below)
+- Any brand constraints? (colors, fonts, tone)
+- How many variations? (default: 5)
+
+Give the page a short kebab-case name for the folder (e.g., `landing-page`, `pricing`,
+`signup-flow`). Confirm the name with the user if it's ambiguous.
+
+## Step 2: Project configuration
+
+Look for `.web-prototype.json` in the project root. If it doesn't exist, create it:
+
+```json
+{
+  "outputRoot": "prototypes",
+  "pages": {}
+}
+```
+
+Ask the user if `prototypes/` is the right output directory. If they want something
+different, use their preference.
+
+When generating a new page, add an entry to `pages`:
+
+```json
+{
+  "outputRoot": "prototypes",
+  "pages": {
+    "landing-page": {
+      "variants": 5,
+      "created": "2026-03-07",
+      "description": "Main marketing landing page"
+    }
+  }
+}
+```
+
+The output structure is:
+```
+{outputRoot}/
+  {page-name}/
+    variant-1.html
+    variant-2.html
+    ...
+    variant-N.html
+```
+
+## Step 3: Generate variations
+
+For each variation, use the `frontend-design` skill to produce a distinctive,
+production-grade design. The critical goal is **maximum visual diversity** — each
+variant should feel like it came from a different designer with a different aesthetic
+philosophy.
+
+### Diversity strategy
+
+Before generating, plan N distinct design directions. Vary these dimensions across
+the set so that no two variants share the same combination:
+
+- **Layout**: single-column, split-screen, asymmetric grid, full-bleed sections,
+  card-based, editorial/magazine, bento grid
+- **Visual tone**: minimal/stark, bold/maximalist, organic/soft, geometric/precise,
+  editorial/typographic, dark/moody, light/airy, retro/vintage, futuristic/glassmorphic
+- **Color approach**: monochromatic, complementary, analogous, high-contrast,
+  muted/earthy, vibrant/saturated, dark mode, light mode
+- **Typography**: large display type, classic serif, geometric sans, mixed type scales,
+  monospace accents, handwritten touches
+- **Motion/interaction**: static, subtle hover effects, scroll-triggered animations,
+  parallax, micro-interactions
+- **Spacing/density**: generous whitespace, dense/information-rich, mixed rhythm
+
+Write out your plan (which direction each variant will take) before generating code.
+Present it to the user for approval. Then generate each variant.
+
+### Per-variant requirements
+
+Each variant must be:
+- A single, self-contained HTML file with all CSS and JS inline
+- Responsive (works on mobile and desktop)
+- Production-grade visual quality — not a wireframe, not a generic template
+- Populated with realistic placeholder content (not lorem ipsum — write real-sounding
+  headlines, descriptions, and data)
+
+### Using the frontend-design skill
+
+For each variant, invoke the frontend-design skill with clear direction about the
+specific aesthetic you're targeting for that variant. Tell it the design direction
+(e.g., "Create a bold maximalist landing page with large typography and vibrant
+complementary colors") so that each invocation produces a genuinely different result.
+
+## Step 4: Inject the variant navigation bar
+
+Every generated HTML file must include the variant navigation bar. This is a floating
+pill-shaped bar at the bottom-right of the viewport that lets the user click between
+variants.
+
+### Navigation bar HTML and CSS
+
+Insert this exactly at the end of `<body>`, before `</body>`. Replace `{N}` with the
+total variant count and set the correct `href` values and `active` class.
+
+```html
+<!-- Variant Navigation -->
+<nav class="variant-nav" aria-label="Design variants">
+  <a href="variant-1.html" class="active" aria-current="page">1</a>
+  <a href="variant-2.html">2</a>
+  <a href="variant-3.html">3</a>
+  <!-- ... up to N -->
+</nav>
+<style>
+  .variant-nav {
+    position: fixed;
+    bottom: 24px;
+    right: 24px;
+    display: flex;
+    gap: 4px;
+    padding: 6px;
+    background: rgba(20, 20, 20, 0.55);
+    backdrop-filter: blur(24px) saturate(180%);
+    -webkit-backdrop-filter: blur(24px) saturate(180%);
+    border-radius: 20px;
+    border: 1px solid rgba(255, 255, 255, 0.15);
+    box-shadow:
+      0 8px 32px rgba(0, 0, 0, 0.18),
+      0 2px 8px rgba(0, 0, 0, 0.1),
+      inset 0 0.5px 0 rgba(255, 255, 255, 0.2);
+    z-index: 2147483647;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif;
+    transition: opacity 0.3s ease;
+  }
+  .variant-nav:hover {
+    background: rgba(20, 20, 20, 0.7);
+  }
+  .variant-nav a {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 36px;
+    height: 36px;
+    border-radius: 12px;
+    text-decoration: none;
+    font-size: 14px;
+    font-weight: 500;
+    letter-spacing: -0.01em;
+    color: rgba(255, 255, 255, 0.7);
+    text-shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
+    transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+    background: transparent;
+    border: 1px solid transparent;
+  }
+  .variant-nav a:hover {
+    background: rgba(255, 255, 255, 0.12);
+    color: rgba(255, 255, 255, 0.95);
+    border-color: rgba(255, 255, 255, 0.08);
+  }
+  .variant-nav a.active {
+    background: rgba(255, 255, 255, 0.2);
+    color: #fff;
+    font-weight: 600;
+    border-color: rgba(255, 255, 255, 0.15);
+    box-shadow:
+      0 2px 8px rgba(0, 0, 0, 0.15),
+      inset 0 0.5px 0 rgba(255, 255, 255, 0.25);
+  }
+</style>
+```
+
+This dark-tinted glass style is intentionally designed to be legible on any background —
+light pages, dark pages, images, gradients, anything. Do not modify the nav bar styles
+to match the page design. The nav bar should look identical across all variants.
+
+Set `aria-current="page"` and the `active` class on whichever variant number matches
+the current file (variant-1.html gets `active` on the "1" link, etc.).
+
+## Feature Library
+
+When the user mentions any of these features by name, you already know what they mean.
+Apply the implementation details described here without requiring further explanation
+from the user.
+
+### Scrolling Parallax
+
+**Trigger phrases**: "parallax", "scrolling parallax", "web parallax", "parallax scrolling",
+"depth scrolling"
+
+Multi-layer parallax scrolling where background elements move at different speeds than
+foreground content during scroll, creating an illusion of depth.
+
+**Implementation approach** (choose based on complexity needs):
+
+**CSS-only (simpler, good for 2-3 layers):**
+```css
+.parallax-container {
+  perspective: 1px;
+  height: 100vh;
+  overflow-x: hidden;
+  overflow-y: auto;
+}
+.parallax-layer-back {
+  transform: translateZ(-2px) scale(3);
+}
+.parallax-layer-mid {
+  transform: translateZ(-1px) scale(2);
+}
+.parallax-layer-front {
+  transform: translateZ(0);
+}
+```
+
+**JavaScript (smoother, more control, good for complex effects):**
+- Use `requestAnimationFrame` for smooth 60fps updates
+- Track scroll position with a passive scroll listener
+- Apply `transform: translate3d(0, Ypx, 0)` to layers at different rates (e.g.,
+  background at 0.3x scroll speed, midground at 0.6x, foreground at 1x)
+- Use `will-change: transform` on animated elements for GPU acceleration
+- Consider `IntersectionObserver` to only animate visible sections
+
+**Design considerations:**
+- Parallax works best with distinct visual sections/bands
+- Use high-quality background images or gradient layers
+- Ensure content remains readable — parallax is decoration, not the content itself
+- Disable or reduce parallax on mobile (`prefers-reduced-motion` media query)
+- Add `@media (prefers-reduced-motion: reduce)` to disable parallax for accessibility
+
+---
+
+## Notes
+
+- If the user asks for more variants of an existing page, read the config to find the
+  current count, generate additional variants, and update the nav bar in ALL files to
+  include the new total.
+- If the user wants to iterate on a specific variant, make edits to that file directly
+  rather than regenerating from scratch.
+- Always confirm the output path with the user before writing files.