flight-rules 0.5.9

package/README.md

@@ -0,0 +1,270 @@
+# Flight Rules
+
+> **Early Development**: This project is in active development (v0.x). APIs and conventions may change between versions. Install with the `dev` tag.
+
+An opinionated framework for AI-assisted software development. Provides conventions for docs, implementation specs, and coding session workflows that both humans and agents can navigate.
+
+The goal:  
+Any agent (or person) should be able to open a project that uses Flight Rules and understand:
+
+- What the project is trying to do
+- How the implementation is structured
+- What has already been done
+- What should happen next
+- What we've learned along the way
+
+---
+
+## Quick Start
+
+Install the CLI globally:
+
+```bash
+npm install -g flight-rules@dev
+```
+
+Then initialize Flight Rules in any project:
+
+```bash
+cd your-project
+flight-rules init
+```
+
+Or run directly without installing:
+
+```bash
+npx flight-rules@dev init
+```
+
+The `init` command will:
+- Create a `.flight-rules/` directory with framework files
+- Optionally create a `docs/` directory with project documentation from templates
+- Optionally generate agent adapters (AGENTS.md for Cursor, CLAUDE.md for Claude Code, etc.)
+
+---
+
+## How It Works
+
+Flight Rules gives your project a structured documentation system that AI agents (and humans) can navigate consistently.
+
+### Project Structure
+
+| Location | Purpose |
+|----------|---------|
+| `.flight-rules/` | Framework files (replaced on upgrade) |
+| `docs/` | Your project documentation (new templates added on upgrade, existing files preserved) |
+
+**Inside `.flight-rules/`:**
+
+| Directory | Purpose |
+|-----------|---------|
+| `AGENTS.md` | Guidelines for AI agents working on your project |
+| `doc-templates/` | Templates for creating project docs |
+| `commands/` | Workflow commands (start/end coding session) |
+| `prompts/` | Reusable prompt templates |
+
+### Implementation Specs (Single Source of Truth)
+
+Implementation specs live in `docs/implementation/` and follow a three-level hierarchy:
+
+| Level | Name | Example | Description |
+|-------|------|---------|-------------|
+| 1 | **Area** | `1-foundation-shell/` | A major implementation area |
+| 2 | **Task Group** | `1.4-application-shell.md` | A file containing related tasks |
+| 3 | **Task** | `1.4.1. Routing Structure` | A specific unit of work with status |
+
+**Key principle:** The spec is the single source of truth. If code diverges from spec, update the spec.
+
+### Coding Sessions
+
+Flight Rules distinguishes between:
+
+- **Ad-hoc requests** — "Change function X in file Y"
+- **Structured sessions** — Follow a start/end ritual with documentation
+
+Two core flows:
+
+- **`dev-session.start`** — Review context, set goals, create a plan
+- **`dev-session.end`** — Summarize work, update progress, capture learnings
+
+Agents don't start these flows on their own; you explicitly invoke them.
+
+### Versioning
+
+Each project tracks which Flight Rules version it uses:
+
+```
+flight_rules_version: 0.1.2
+```
+
+This appears in `.flight-rules/AGENTS.md` and helps coordinate upgrades.
+
+---
+
+## What Gets Installed
+
+When you run `flight-rules init`, you get:
+
+```text
+your-project/
+├── AGENTS.md                 # (Optional) Adapter for Cursor - points to .flight-rules/
+├── docs/                     # YOUR content (new templates added on upgrade)
+│   ├── prd.md
+│   ├── progress.md
+│   ├── critical-learnings.md
+│   ├── tech-stack.md
+│   ├── implementation/
+│   │   └── overview.md
+│   └── session_logs/
+└── .flight-rules/            # Framework files (can be replaced on upgrade)
+    ├── AGENTS.md             # Agent guidelines
+    ├── doc-templates/        # Templates for creating your docs
+    │   ├── prd.md
+    │   ├── progress.md
+    │   ├── critical-learnings.md
+    │   ├── tech-stack.md
+    │   ├── session-log.md
+    │   └── implementation/
+    │       └── overview.md
+    ├── commands/
+    │   ├── dev-session.start.md
+    │   ├── dev-session.end.md
+    │   ├── test.add.md
+    │   └── test.assess-current.md
+    └── prompts/              # Reusable prompt templates
+```
+
+---
+
+## Day-to-Day Usage
+
+### When you open a project
+
+1. Agents should read `.flight-rules/AGENTS.md`
+2. Skim `docs/prd.md` and `docs/implementation/overview.md`
+3. Check `docs/progress.md` for recent work
+
+### For structured work
+
+- **"start coding session"** — Sets goals, creates a plan
+- **"end coding session"** — Summarizes work, updates docs
+
+### When making changes
+
+- Identify relevant Area, Task Group, and Task
+- Update Tasks when reality diverges from plan
+- Keep `Status:` fields current
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `flight-rules init` | Install Flight Rules into a project (interactive setup wizard) |
+| `flight-rules upgrade` | Upgrade Flight Rules in an existing project (preserves your docs) |
+| `flight-rules adapter` | Generate agent-specific adapters (`--cursor`, `--claude`) |
+
+---
+
+## Upgrading
+
+Upgrade Flight Rules while preserving your content:
+
+```bash
+flight-rules upgrade
+```
+
+**What gets replaced:**
+- The `.flight-rules/` directory (framework files)
+
+**What gets added (without overwriting):**
+- New templates are added to `docs/` if they don't already exist
+- Your existing doc files are never modified
+
+---
+
+## Manual Installation
+
+If you prefer not to use the CLI:
+
+1. Clone this repo:
+
+   ```bash
+   git clone https://github.com/ryanpacker/flight-rules.git ~/flight-rules
+   ```
+
+2. Copy the payload into your project:
+
+   ```bash
+   cp -R ~/flight-rules/payload /path/to/your/project/.flight-rules
+   ```
+
+3. Create a `docs/` directory and copy templates from `.flight-rules/doc-templates/` to customize them.
+
+---
+
+## Future Directions
+
+- **Skills/MCP integration** — Conventions for documenting tools and workflows
+- **Hosted planning systems** — Potential integration with Linear, etc.
+- **v1.0 stability** — Stabilizing APIs and conventions for a production-ready release
+
+Current focus:
+
+- A solid, Markdown-based structure
+- Clear expectations for agents
+- CLI tooling for easy installation and upgrades
+
+---
+
+## Contributing
+
+This repo is an npm package with the following structure:
+
+| Path | Purpose |
+|------|---------|
+| `src/` | CLI source code (TypeScript) |
+| `dist/` | Compiled CLI (committed for GitHub installs) |
+| `payload/` | The content delivered to projects as `.flight-rules/` |
+| `scripts/` | Build and release utilities |
+
+### Development
+
+```bash
+git clone https://github.com/ryanpacker/flight-rules.git
+cd flight-rules
+npm install
+npm run build
+```
+
+### Testing
+
+The project uses [Vitest](https://vitest.dev/) for testing with ~93% code coverage.
+
+```bash
+npm test              # Run tests once
+npm run test:watch    # Watch mode for development
+npm run test:coverage # Generate coverage report
+```
+
+Tests are located in `tests/` and mirror the `src/` structure:
+
+| Test File | Coverage |
+|-----------|----------|
+| `tests/utils/files.test.ts` | 100% |
+| `tests/commands/init.test.ts` | 98.5% |
+| `tests/commands/upgrade.test.ts` | 100% |
+| `tests/commands/adapter.test.ts` | 79% |
+
+### Releasing
+
+```bash
+npm version patch   # or minor/major
+git push && git push --tags
+npm publish --tag dev
+```
+
+This automatically builds, syncs the version to `payload/AGENTS.md`, creates a tagged commit, and publishes to npm.
+
+> **Note:** Until v1.0, all releases use the `dev` tag. Users install with `npm install -g flight-rules@dev`.

package/dist/commands/adapter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Copy command files to a destination directory with conflict handling
+ */
+export declare function copyCommandsWithConflictHandling(sourceDir: string, destDir: string, skipPrompts?: boolean): Promise<{
+    copied: string[];
+    skipped: string[];
+}>;
+/**
+ * Setup Cursor-specific directories and commands
+ */
+export declare function setupCursorCommands(cwd: string, sourceCommandsDir: string, skipPrompts?: boolean): Promise<{
+    copied: string[];
+    skipped: string[];
+}>;
+/**
+ * Check if Cursor adapter is installed (has .cursor/commands/)
+ */
+export declare function isCursorAdapterInstalled(cwd: string): boolean;
+/**
+ * Setup Claude Code-specific directories and commands
+ */
+export declare function setupClaudeCommands(cwd: string, sourceCommandsDir: string, skipPrompts?: boolean): Promise<{
+    copied: string[];
+    skipped: string[];
+}>;
+/**
+ * Check if Claude Code adapter is installed (has .claude/commands/)
+ */
+export declare function isClaudeAdapterInstalled(cwd: string): boolean;
+/**
+ * Check if a specific adapter file exists
+ */
+export declare function isAdapterInstalled(cwd: string, adapterKey: string): boolean;
+export declare function adapter(args: string[]): Promise<void>;
+export declare function generateAdapters(adapterNames: string[], sourceCommandsDir?: string, interactive?: boolean): Promise<void>;

package/dist/commands/adapter.js

@@ -0,0 +1,308 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { writeFileSync, existsSync, readdirSync, cpSync } from 'fs';
+import { join } from 'path';
+import { ensureDir, getFlightRulesDir } from '../utils/files.js';
+import { isInteractive } from '../utils/interactive.js';
+const ADAPTERS = {
+    cursor: {
+        name: 'Cursor',
+        filename: 'AGENTS.md',
+        title: 'Flight Rules – Cursor Adapter',
+        description: 'This file is placed at the project root as `AGENTS.md` for Cursor compatibility.',
+        hasNativeCommands: true,
+        commandsDirectory: '.cursor/commands',
+    },
+    claude: {
+        name: 'Claude Code',
+        filename: 'CLAUDE.md',
+        title: 'Flight Rules – Claude Code Adapter',
+        description: 'This file is placed at the project root as `CLAUDE.md` for Claude Code compatibility.',
+        hasNativeCommands: true,
+        commandsDirectory: '.claude/commands',
+    },
+};
+function generateAdapterContent(config) {
+    // Adapter-specific command instructions
+    const commandLocation = config.hasNativeCommands && config.commandsDirectory
+        ? `\`${config.commandsDirectory}/\` (as slash commands)`
+        : `\`.flight-rules/commands/\``;
+    const commandInstructions = config.hasNativeCommands
+        ? `Use the \`/dev-session.start\` and \`/dev-session.end\` slash commands.`
+        : `When the user says "start coding session" or "end coding session", follow the instructions in \`.flight-rules/commands/\`.`;
+    return `# ${config.title}
+
+${config.description}
+
+---
+
+**This project uses Flight Rules.**
+
+Agent guidelines and workflows live in \`.flight-rules/\`. Project documentation lives in \`docs/\`.
+
+## Quick Reference
+
+| What | Where |
+|------|-------|
+| Agent Guidelines | \`.flight-rules/AGENTS.md\` |
+| PRD | \`docs/prd.md\` |
+| Implementation Specs | \`docs/implementation/\` |
+| Progress Log | \`docs/progress.md\` |
+| Tech Stack | \`docs/tech-stack.md\` |
+| Session Commands | ${commandLocation} |
+
+## For Agents
+
+Please read \`.flight-rules/AGENTS.md\` for complete guidelines on:
+- Project structure
+- Implementation specs
+- Coding sessions
+- How to work with this system
+
+${commandInstructions}
+`;
+}
+/**
+ * Copy command files to a destination directory with conflict handling
+ */
+export async function copyCommandsWithConflictHandling(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)) {
+            // File already exists - need to handle conflict
+            if (skipPrompts) {
+                // During upgrade with no prompts, replace by default
+                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;
+            }
+            // Prompt for this specific file
+            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 {
+            // No conflict - just copy
+            cpSync(srcPath, destPath);
+            copied.push(file);
+        }
+    }
+    return { copied, skipped };
+}
+/**
+ * Prompt user for how to handle a file conflict
+ */
+async function promptForConflict(filename, showBatchOptions) {
+    const options = [
+        { value: 'replace', label: 'Replace', hint: 'overwrite with Flight Rules version' },
+        { value: 'skip', label: 'Skip', hint: 'keep existing file' },
+    ];
+    if (showBatchOptions) {
+        options.push({ value: 'replace_all', label: 'Replace all', hint: 'replace this and all remaining conflicts' }, { value: 'skip_all', label: 'Skip all', hint: 'skip this and all remaining conflicts' });
+    }
+    const action = await p.select({
+        message: `${pc.cyan(filename)} already exists. What would you like to do?`,
+        options,
+    });
+    if (p.isCancel(action)) {
+        return 'skip';
+    }
+    return action;
+}
+/**
+ * Setup Cursor-specific directories and commands
+ */
+export async function setupCursorCommands(cwd, sourceCommandsDir, skipPrompts = false) {
+    const cursorDir = join(cwd, '.cursor');
+    const cursorCommandsDir = join(cursorDir, 'commands');
+    // Create directories
+    ensureDir(cursorDir);
+    ensureDir(cursorCommandsDir);
+    // Copy commands with conflict handling
+    return copyCommandsWithConflictHandling(sourceCommandsDir, cursorCommandsDir, skipPrompts);
+}
+/**
+ * Check if Cursor adapter is installed (has .cursor/commands/)
+ */
+export function isCursorAdapterInstalled(cwd) {
+    return existsSync(join(cwd, '.cursor', 'commands'));
+}
+/**
+ * Setup Claude Code-specific directories and commands
+ */
+export async function setupClaudeCommands(cwd, sourceCommandsDir, skipPrompts = false) {
+    const claudeDir = join(cwd, '.claude');
+    const claudeCommandsDir = join(claudeDir, 'commands');
+    // Create directories
+    ensureDir(claudeDir);
+    ensureDir(claudeCommandsDir);
+    // Copy commands with conflict handling
+    return copyCommandsWithConflictHandling(sourceCommandsDir, claudeCommandsDir, skipPrompts);
+}
+/**
+ * Check if Claude Code adapter is installed (has .claude/commands/)
+ */
+export function isClaudeAdapterInstalled(cwd) {
+    return existsSync(join(cwd, '.claude', 'commands'));
+}
+/**
+ * Check if a specific adapter file exists
+ */
+export function isAdapterInstalled(cwd, adapterKey) {
+    const config = ADAPTERS[adapterKey];
+    if (!config)
+        return false;
+    if (adapterKey === 'cursor') {
+        // For Cursor, check both AGENTS.md and .cursor/commands/
+        return existsSync(join(cwd, config.filename)) || isCursorAdapterInstalled(cwd);
+    }
+    if (adapterKey === 'claude') {
+        // For Claude, check both CLAUDE.md and .claude/commands/
+        return existsSync(join(cwd, config.filename)) || isClaudeAdapterInstalled(cwd);
+    }
+    return existsSync(join(cwd, config.filename));
+}
+export async function adapter(args) {
+    const cwd = process.cwd();
+    const interactive = isInteractive();
+    // Parse arguments
+    let selectedAdapters = [];
+    if (args.includes('--all')) {
+        selectedAdapters = Object.keys(ADAPTERS);
+    }
+    else {
+        for (const arg of args) {
+            const adapterName = arg.replace('--', '');
+            if (ADAPTERS[adapterName]) {
+                selectedAdapters.push(adapterName);
+            }
+        }
+    }
+    // If no adapters specified via args, prompt for selection (or error in non-interactive)
+    if (selectedAdapters.length === 0) {
+        if (!interactive) {
+            // Non-interactive: require explicit adapter flags
+            p.log.error('No adapters specified. In non-interactive mode, use:');
+            console.log('  flight-rules adapter --cursor');
+            console.log('  flight-rules adapter --claude');
+            console.log('  flight-rules adapter --all');
+            process.exit(1);
+        }
+        const selection = await p.multiselect({
+            message: 'Which adapters would you like to generate?',
+            options: Object.entries(ADAPTERS).map(([key, config]) => ({
+                value: key,
+                label: config.commandsDirectory
+                    ? `${config.name} (${config.filename} + ${config.commandsDirectory}/)`
+                    : `${config.name} (${config.filename})`,
+                hint: key === 'cursor' ? 'recommended' : undefined,
+            })),
+            initialValues: ['cursor'],
+        });
+        if (p.isCancel(selection)) {
+            p.log.info('Cancelled.');
+            return;
+        }
+        selectedAdapters = selection;
+    }
+    await generateAdapters(selectedAdapters, undefined, interactive);
+}
+export async function generateAdapters(adapterNames, sourceCommandsDir, interactive = true) {
+    const cwd = process.cwd();
+    // Default to .flight-rules/commands if no source specified
+    const commandsDir = sourceCommandsDir ?? join(getFlightRulesDir(cwd), 'commands');
+    for (const name of adapterNames) {
+        const config = ADAPTERS[name];
+        if (!config)
+            continue;
+        const filePath = join(cwd, config.filename);
+        let adapterFileWritten = false;
+        // Check if file already exists
+        if (existsSync(filePath)) {
+            if (interactive) {
+                const overwrite = await p.confirm({
+                    message: `${config.filename} already exists. Overwrite?`,
+                    initialValue: false,
+                });
+                if (p.isCancel(overwrite) || !overwrite) {
+                    p.log.info(`Skipped ${config.filename}`);
+                    // Don't continue - still need to set up commands directory
+                }
+                else {
+                    const content = generateAdapterContent(config);
+                    writeFileSync(filePath, content, 'utf-8');
+                    p.log.success(`Updated ${pc.cyan(config.filename)} for ${config.name}`);
+                    adapterFileWritten = true;
+                }
+            }
+            else {
+                // Non-interactive: skip overwrite (safe default)
+                p.log.info(`Skipped ${config.filename} (already exists)`);
+                // Don't continue - still need to set up commands directory
+            }
+        }
+        else {
+            const content = generateAdapterContent(config);
+            writeFileSync(filePath, content, 'utf-8');
+            p.log.success(`Created ${pc.cyan(config.filename)} for ${config.name}`);
+            adapterFileWritten = true;
+        }
+        // For Cursor, also set up .cursor/commands/
+        if (name === 'cursor') {
+            const skipPrompts = !interactive;
+            const commandsDirExists = isCursorAdapterInstalled(cwd);
+            const result = await setupCursorCommands(cwd, commandsDir, skipPrompts);
+            if (result.copied.length > 0) {
+                const action = commandsDirExists ? 'Updated' : 'Created';
+                p.log.success(`${action} ${pc.cyan('.cursor/commands/')} with ${result.copied.length} command(s)`);
+            }
+            if (result.skipped.length > 0) {
+                p.log.info(`Skipped ${result.skipped.length} existing command(s) in .cursor/commands/`);
+            }
+        }
+        // For Claude, also set up .claude/commands/
+        if (name === 'claude') {
+            const skipPrompts = !interactive;
+            const commandsDirExists = isClaudeAdapterInstalled(cwd);
+            const result = await setupClaudeCommands(cwd, commandsDir, skipPrompts);
+            if (result.copied.length > 0) {
+                const action = commandsDirExists ? 'Updated' : 'Created';
+                p.log.success(`${action} ${pc.cyan('.claude/commands/')} with ${result.copied.length} command(s)`);
+            }
+            if (result.skipped.length > 0) {
+                p.log.info(`Skipped ${result.skipped.length} existing command(s) in .claude/commands/`);
+            }
+        }
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function init(): Promise<void>;