flight-rules 0.13.8 → 0.13.9

package/dist/commands/ralph.d.ts

@@ -5,6 +5,27 @@ export interface RalphOptions {
     area?: string;
     branch?: string | boolean;
 }
+export interface TaskGroupPlan {
+    id: string;
+    title: string;
+    filePath: string;
+    area: string;
+    incompleteTasks: Array<{
+        id: string;
+        title: string;
+        status: string;
+    }>;
+}
+/**
+ * Parse the discovery response from Claude into TaskGroupPlan objects.
+ * Returns null if the response cannot be parsed (tags not found).
+ * Returns empty array if ALL_COMPLETE.
+ */
+export declare function parseDiscoveryResponse(output: string): TaskGroupPlan[] | null;
+/**
+ * Build an execution prompt from the template and a task group plan.
+ */
+export declare function buildExecutionPrompt(template: string, taskGroup: TaskGroupPlan): string;
 /**
  * Run the Ralph Loop - an autonomous agent loop that works through task groups
  */

package/dist/commands/ralph.js

@@ -4,7 +4,6 @@ import { spawn } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { isFlightRulesInstalled, getFlightRulesDir } from '../utils/files.js';
-const COMPLETION_SIGNAL = '<ralph-signal>COMPLETE</ralph-signal>';
 /**
  * Generate a default branch name for Ralph work
  */
@@ -65,7 +64,7 @@ async function createAndCheckoutBranch(branchName) {
     return { success: true };
 }
 /**
- * Build area constraint text to append to prompt
+ * Build area constraint text to append to discovery prompt
  */
 function buildAreaConstraint(area) {
     return `
@@ -78,7 +77,7 @@ function buildAreaConstraint(area) {
 
 - Only scan \`docs/implementation/${area}*/\` for task groups
 - Ignore all other areas
-- If no incomplete task groups exist in Area ${area}, output the completion signal
+- If no incomplete task groups exist in Area ${area}, respond with ALL_COMPLETE
 `;
 }
 /**
@@ -177,23 +176,93 @@ async function runClaudeWithPrompt(promptContent, verbose) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Parse the discovery response from Claude into TaskGroupPlan objects.
+ * Returns null if the response cannot be parsed (tags not found).
+ * Returns empty array if ALL_COMPLETE.
+ */
+export function parseDiscoveryResponse(output) {
+    // Extract content between <ralph-discovery> tags
+    const match = output.match(/<ralph-discovery>([\s\S]*?)<\/ralph-discovery>/);
+    if (!match) {
+        return null;
+    }
+    const content = match[1].trim();
+    // Handle ALL_COMPLETE case
+    if (content === 'ALL_COMPLETE') {
+        return [];
+    }
+    const taskGroups = [];
+    let currentGroup = null;
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (trimmed.startsWith('TASK_GROUP|')) {
+            const parts = trimmed.split('|');
+            if (parts.length >= 5) {
+                currentGroup = {
+                    id: parts[1],
+                    title: parts[2],
+                    filePath: parts[3],
+                    area: parts[4],
+                    incompleteTasks: [],
+                };
+                taskGroups.push(currentGroup);
+            }
+        }
+        else if (trimmed.startsWith('TASK|') && currentGroup) {
+            const parts = trimmed.split('|');
+            if (parts.length >= 4) {
+                currentGroup.incompleteTasks.push({
+                    id: parts[1],
+                    title: parts[2],
+                    status: parts[3],
+                });
+            }
+        }
+        // Skip malformed lines silently
+    }
+    return taskGroups;
+}
+/**
+ * Build an execution prompt from the template and a task group plan.
+ */
+export function buildExecutionPrompt(template, taskGroup) {
+    // Render incomplete tasks as markdown bullet points
+    const tasksList = taskGroup.incompleteTasks
+        .map((t) => `- **${t.id}**: ${t.title} (${t.status})`)
+        .join('\n');
+    return template
+        .replace(/\{\{TASK_GROUP_ID\}\}/g, taskGroup.id)
+        .replace(/\{\{TASK_GROUP_TITLE\}\}/g, taskGroup.title)
+        .replace(/\{\{TASK_GROUP_FILE_PATH\}\}/g, taskGroup.filePath)
+        .replace(/\{\{INCOMPLETE_TASKS_LIST\}\}/g, tasksList);
+}
 /**
  * Run the Ralph Loop - an autonomous agent loop that works through task groups
  */
 export async function ralph(options) {
     const cwd = process.cwd();
     const flightRulesDir = getFlightRulesDir(cwd);
-    const promptPath = join(flightRulesDir, 'prompts', 'ralph-loop.md');
+    const discoveryPromptPath = join(flightRulesDir, 'prompts', 'ralph-discovery.md');
+    const executionPromptPath = join(flightRulesDir, 'prompts', 'ralph-execution.md');
     // Verify Flight Rules is installed
     if (!isFlightRulesInstalled(cwd)) {
         p.log.error('Flight Rules is not installed in this directory.');
         p.log.info('Run `flight-rules init` first.');
         return;
     }
-    // Verify prompt file exists
-    if (!existsSync(promptPath)) {
-        p.log.error('Ralph prompt file not found.');
-        p.log.info(`Expected at: ${promptPath}`);
+    // Verify both prompt files exist
+    if (!existsSync(discoveryPromptPath)) {
+        p.log.error('Ralph discovery prompt file not found.');
+        p.log.info(`Expected at: ${discoveryPromptPath}`);
+        p.log.info('You may need to run `flight-rules upgrade` to get the latest files.');
+        return;
+    }
+    if (!existsSync(executionPromptPath)) {
+        p.log.error('Ralph execution prompt file not found.');
+        p.log.info(`Expected at: ${executionPromptPath}`);
         p.log.info('You may need to run `flight-rules upgrade` to get the latest files.');
         return;
     }
@@ -204,10 +273,12 @@ export async function ralph(options) {
         p.log.info('Install it with: npm install -g @anthropic-ai/claude-code');
         return;
     }
-    // Read the prompt content and optionally append area constraint
-    let promptContent = readFileSync(promptPath, 'utf-8');
+    // Read prompt files
+    let discoveryPrompt = readFileSync(discoveryPromptPath, 'utf-8');
+    const executionTemplate = readFileSync(executionPromptPath, 'utf-8');
+    // Optionally append area constraint to discovery prompt
     if (options.area) {
-        promptContent += buildAreaConstraint(options.area);
+        discoveryPrompt += buildAreaConstraint(options.area);
     }
     // Determine branch name if branching is requested
     let branchName;
@@ -217,15 +288,17 @@ export async function ralph(options) {
     // Dry run mode
     if (options.dryRun) {
         p.log.info(pc.yellow('Dry run mode - showing what would be executed:'));
-        p.log.message(`  Prompt file: ${promptPath}`);
-        p.log.message(`  Max iterations: ${options.maxIterations}`);
+        p.log.message(`  Discovery prompt: ${discoveryPromptPath}`);
+        p.log.message(`  Execution prompt: ${executionPromptPath}`);
+        p.log.message(`  Max task groups: ${options.maxIterations}`);
         if (options.area) {
             p.log.message(`  Area constraint: ${options.area}`);
         }
         if (branchName) {
             p.log.message(`  Branch: ${branchName}`);
         }
-        p.log.message(`  Command: claude --dangerously-skip-permissions -p < "${promptPath}"`);
+        p.log.message('  Phase 1: Discovery — identify incomplete task groups');
+        p.log.message('  Phase 2: Execution — one Claude instance per task group');
         return;
     }
     // Handle branch creation if requested
@@ -249,7 +322,7 @@ export async function ralph(options) {
     // Start the loop
     console.log();
     p.intro(pc.bgMagenta(pc.white(' Flight Rules Ralph Loop ')));
-    p.log.info(`Starting autonomous loop with max ${options.maxIterations} iterations`);
+    p.log.info(`Two-phase mode: discover then execute (max ${options.maxIterations} task groups)`);
     if (options.area) {
         p.log.info(`Targeting Area: ${pc.cyan(options.area)}`);
     }
@@ -258,40 +331,97 @@ export async function ralph(options) {
     }
     p.log.warn('Press Ctrl+C to stop the loop at any time');
     console.log();
-    for (let i = 1; i <= options.maxIterations; i++) {
+    // ── Phase 1: Discovery ──────────────────────────────────────────────
+    p.log.step(pc.magenta('Phase 1: Discovery'));
+    p.log.info('Scanning implementation docs for incomplete task groups...');
+    console.log();
+    let taskGroups;
+    try {
+        const discoveryResult = await runClaudeWithPrompt(discoveryPrompt, options.verbose);
+        if (discoveryResult.exitCode !== 0) {
+            p.log.warn(`Discovery phase exited with code ${discoveryResult.exitCode}`);
+        }
+        const parsed = parseDiscoveryResponse(discoveryResult.output);
+        if (parsed === null) {
+            p.log.error('Could not parse discovery response. Expected <ralph-discovery> tags.');
+            p.log.info('Run with --verbose to see the full Claude output.');
+            p.outro(pc.red('Ralph loop aborted'));
+            return;
+        }
+        taskGroups = parsed;
+    }
+    catch (error) {
+        p.log.error(`Discovery phase failed: ${error instanceof Error ? error.message : String(error)}`);
+        p.outro(pc.red('Ralph loop aborted'));
+        return;
+    }
+    // Handle ALL_COMPLETE
+    if (taskGroups.length === 0) {
+        console.log();
+        p.log.success(pc.green('All task groups complete!'));
+        p.outro(pc.green('Ralph loop finished — nothing to do'));
+        return;
+    }
+    // Display discovered task groups
+    console.log();
+    p.log.info(`Found ${taskGroups.length} incomplete task group(s):`);
+    for (const tg of taskGroups) {
+        p.log.message(`  ${pc.cyan(tg.id)} — ${tg.title} (${tg.incompleteTasks.length} tasks)`);
+    }
+    console.log();
+    // Limit to max iterations
+    const groupsToExecute = taskGroups.slice(0, options.maxIterations);
+    if (taskGroups.length > options.maxIterations) {
+        p.log.info(`Will execute ${options.maxIterations} of ${taskGroups.length} task groups (--max-iterations)`);
+        console.log();
+    }
+    // ── Phase 2: Execution ──────────────────────────────────────────────
+    p.log.step(pc.magenta('Phase 2: Execution'));
+    console.log();
+    let completed = 0;
+    let failed = 0;
+    for (let i = 0; i < groupsToExecute.length; i++) {
+        const taskGroup = groupsToExecute[i];
         const separator = '='.repeat(50);
         p.log.step(pc.dim(separator));
-        p.log.step(pc.magenta(`  Ralph Iteration ${i} of ${options.maxIterations}`));
+        p.log.step(pc.magenta(`  Task Group ${i + 1} of ${groupsToExecute.length}: ${taskGroup.id} — ${taskGroup.title}`));
         p.log.step(pc.dim(separator));
         console.log();
         try {
-            const result = await runClaudeWithPrompt(promptContent, options.verbose);
-            // Check for completion signal
-            if (result.output.includes(COMPLETION_SIGNAL)) {
-                console.log();
-                p.log.success(pc.green('All task groups complete!'));
-                p.log.info(`Finished at iteration ${i} of ${options.maxIterations}`);
-                p.outro(pc.green('Ralph loop finished successfully'));
-                return;
-            }
+            const executionPrompt = buildExecutionPrompt(executionTemplate, taskGroup);
+            const result = await runClaudeWithPrompt(executionPrompt, options.verbose);
             if (result.exitCode !== 0) {
-                p.log.warn(`Claude exited with code ${result.exitCode}`);
+                p.log.warn(`Task group ${taskGroup.id} exited with code ${result.exitCode}`);
+                failed++;
             }
-            p.log.info(`Iteration ${i} complete. Continuing...`);
-            // Small delay between iterations to allow for any cleanup
-            if (i < options.maxIterations) {
-                await sleep(2000);
+            else {
+                p.log.success(`Task group ${taskGroup.id} complete`);
+                completed++;
             }
         }
         catch (error) {
-            p.log.error(`Error in iteration ${i}: ${error instanceof Error ? error.message : String(error)}`);
-            // Continue to next iteration despite errors
+            p.log.error(`Error executing task group ${taskGroup.id}: ${error instanceof Error ? error.message : String(error)}`);
+            failed++;
+            // Continue to next task group despite errors
+        }
+        // Small delay between executions
+        if (i < groupsToExecute.length - 1) {
+            await sleep(2000);
         }
     }
-    // Reached max iterations
+    // Summary
     console.log();
-    p.log.warn(`Reached max iterations (${options.maxIterations}) without completing all tasks.`);
-    p.log.info('Check docs/progress.md and docs/ralph_logs/ for current status.');
-    p.log.info('Run `flight-rules ralph` again to continue.');
-    p.outro(pc.yellow('Ralph loop stopped'));
+    const separator = '='.repeat(50);
+    p.log.step(pc.dim(separator));
+    p.log.info(`Summary: ${completed} completed, ${failed} failed out of ${groupsToExecute.length} task groups`);
+    if (taskGroups.length > options.maxIterations) {
+        p.log.info(`${taskGroups.length - options.maxIterations} task group(s) remaining. Run \`flight-rules ralph\` again to continue.`);
+    }
+    if (failed > 0) {
+        p.log.info('Check docs/ralph_logs/ for details on failures.');
+        p.outro(pc.yellow('Ralph loop finished with errors'));
+    }
+    else {
+        p.outro(pc.green('Ralph loop finished successfully'));
+    }
 }

package/dist/index.js

@@ -159,7 +159,7 @@ ${pc.bold('Adapter Options:')}
   --all       Generate all adapters
 
 ${pc.bold('Ralph Options:')}
-  --max-iterations, -n <n>  Maximum iterations before stopping (default: 10)
+  --max-iterations, -n <n>  Maximum task groups to execute (default: 10)
   --area <id>               Focus on a specific implementation area (e.g., 2 or 2-cli-core)
   --branch [name]           Create a new branch before starting (auto-generates if no name)
   --dry-run                 Show what would be executed without running

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flight-rules",
-  "version": "0.13.8",
+  "version": "0.13.9",
   "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.13.8
+flight_rules_version: 0.13.9
 
 This file defines how agents (Claude Code, Cursor, etc.) should work on software projects using the Flight Rules system.
 

package/payload/prompts/ralph-discovery.md

@@ -0,0 +1,50 @@
+# Flight Rules Discovery Agent
+
+You are a discovery agent for Flight Rules. Your ONLY job is to scan implementation docs and report which task groups have incomplete tasks. Do NOT implement anything.
+
+## Instructions
+
+1. Read `docs/implementation/overview.md` to understand the area/task-group structure
+2. Scan each Area directory in `docs/implementation/`
+3. For each Task Group file (.md), check every task's status
+4. Report all task groups that contain any task with status other than ✅ Complete (i.e., 🔵 Planned, 🟡 In Progress, or ⏸️ Blocked)
+
+## Response Format
+
+Respond with a pipe-delimited report inside `<ralph-discovery>` tags. Use EXACTLY this format:
+
+```
+<ralph-discovery>
+TASK_GROUP|{id}|{title}|{filePath}|{areaDir}
+TASK|{taskId}|{taskTitle}|{status}
+TASK|{taskId}|{taskTitle}|{status}
+TASK_GROUP|{id}|{title}|{filePath}|{areaDir}
+TASK|{taskId}|{taskTitle}|{status}
+</ralph-discovery>
+```
+
+- Each `TASK_GROUP` line is followed by its `TASK` lines (only incomplete tasks)
+- `{id}` = task group ID as written in the file (e.g., "1.1", "2.3")
+- `{title}` = task group title
+- `{filePath}` = relative path from project root to the task group file
+- `{areaDir}` = area directory name (e.g., "1-project-setup", "2-cli-core")
+- `{taskId}` = individual task ID (e.g., "1.1.1", "2.3.2")
+- `{taskTitle}` = individual task title
+- `{status}` = one of: planned, in_progress, blocked
+
+If ALL tasks in ALL task groups are ✅ Complete, respond with:
+
+```
+<ralph-discovery>
+ALL_COMPLETE
+</ralph-discovery>
+```
+
+## Rules
+
+- Do NOT implement or modify any code
+- Do NOT create or modify any files
+- Do NOT run any scripts or quality checks
+- ONLY read implementation files and report status
+- Always include the `<ralph-discovery>` tags in your response
+- List task groups in the order they should be worked on (by area number, then task group number)

package/payload/prompts/ralph-execution.md

@@ -0,0 +1,100 @@
+# Flight Rules Autonomous Agent — Scoped Execution
+
+You are an autonomous coding agent implementing a SPECIFIC Flight Rules task group. Work ONLY on the task group described below.
+
+## Your Assignment
+
+**Task Group:** {{TASK_GROUP_ID}} — {{TASK_GROUP_TITLE}}
+**Task Group File:** {{TASK_GROUP_FILE_PATH}}
+
+### Incomplete Tasks
+
+{{INCOMPLETE_TASKS_LIST}}
+
+## Instructions
+
+1. **Preparation**
+   - Read `.flight-rules/AGENTS.md` for framework guidelines
+   - Read `docs/prd.md` for project requirements
+   - Read `docs/progress.md` for recent work history (especially the last entry)
+   - Read `docs/critical-learnings.md` for patterns and gotchas
+   - Read `package.json` to discover available scripts
+   - Read the task group file: `{{TASK_GROUP_FILE_PATH}}`
+
+2. **For EACH incomplete task listed above:**
+   - Update task status to 🟡 In Progress in the task group file
+   - Implement according to the Approach section in the task group file
+   - Run quality checks (see below)
+   - Verify against Acceptance Criteria
+   - Update task status to ✅ Complete
+
+3. **After All Tasks Complete**
+   - Verify the entire Task Group is complete
+   - Create a Ralph log entry (see Logging section)
+   - If you discovered reusable patterns or gotchas, append to `docs/critical-learnings.md`
+   - Commit all changes:
+     ```bash
+     git add -A
+     git commit -m "feat: {{TASK_GROUP_ID}} - {{TASK_GROUP_TITLE}}"
+     ```
+
+4. **Quality Checks (Run Before Every Commit)**
+   Read `package.json` to discover available scripts. Then run the relevant ones:
+   - If `typecheck` or `tsc` script exists: run it
+   - If `test` script exists: run it
+   - If `lint` script exists: run it
+   - If `build` script exists: run it to verify compilation
+
+   All checks must pass before committing. If a check fails, fix the issue and retry.
+
+   If you attempt to fix the same issue 3 times without success, document the blocker in your Ralph log and mark the task as ⏸️ Blocked. Then move to the next task.
+
+## Logging
+
+After completing the task group (or when blocked), create or append to `docs/ralph_logs/YYYYMMDD_HHMM_ralph.md`:
+
+```markdown
+# Ralph Log: YYYY-MM-DD HH:MM
+
+## Task Group: {{TASK_GROUP_ID}} - {{TASK_GROUP_TITLE}}
+
+### Tasks Completed
+- [Task ID]: [Brief description of what was done]
+
+### Files Changed
+- `path/to/file.ts` - [what changed]
+
+### Quality Check Results
+- typecheck: pass/fail (details)
+- test: pass/fail (details)
+- lint: pass/fail (details)
+
+### Blockers (if any)
+- [Description of blocker and attempts made]
+
+### Learnings
+- [Patterns discovered, gotchas encountered]
+```
+
+Also update `docs/progress.md` with a brief entry:
+```markdown
+### YYYY-MM-DD HH:MM - {{TASK_GROUP_ID}} (Ralph)
+- Summary of work done
+- See: ralph_logs/YYYYMMDD_HHMM_ralph.md
+```
+
+## Rules
+
+- Work ONLY on the tasks listed above — do NOT look for other task groups
+- NEVER ask for human input — work autonomously
+- NEVER skip quality checks
+- If blocked after 3 attempts on the same issue, document it and move on
+- Commit after completing all tasks in this group, not after each individual task
+- Keep commits atomic and CI-friendly
+
+## Status Legend
+
+- 🔵 Planned — Not started
+- 🟡 In Progress — Currently being worked on
+- ✅ Complete — Done and verified
+- ⏸️ Blocked — Cannot proceed (document why in Ralph log)

package/payload/prompts/ralph-loop.md

@@ -1,113 +0,0 @@
-# Flight Rules Autonomous Agent
-
-You are an autonomous coding agent implementing Flight Rules task groups.
-
-## Your Mission
-
-1. **Find Next Task Group**
-   - Read `docs/implementation/overview.md`
-   - Scan all Area directories in `docs/implementation/`
-   - Find the first Task Group file (.md) with any task having status 🔵 Planned or 🟡 In Progress
-   - If ALL tasks across ALL task groups are ✅ Complete, proceed to step 2
-   - Otherwise, proceed to step 3
-
-2. **If ALL Tasks in ALL Task Groups Are Complete**
-   - ONLY output the completion signal when you have verified that EVERY task in EVERY task group is ✅ Complete
-   - Output exactly: `<ralph-signal>COMPLETE</ralph-signal>`
-   - Stop immediately - do not output anything else after this
-   - **IMPORTANT**: Do NOT output this signal just because the current task group is done. The loop will automatically continue to the next iteration.
-
-3. **If Task Group Found**
-   - Read the Task Group file completely
-   - For EACH task in the group that is not ✅ Complete:
-     - Update task status to 🟡 In Progress
-     - Implement according to the Approach section
-     - Run quality checks (see below)
-     - Verify against Acceptance Criteria
-     - Update task status to ✅ Complete
-
-4. **After All Tasks in Group Complete**
-   - Verify the entire Task Group is complete
-   - Create a Ralph log entry (see Logging section below)
-   - If you discovered reusable patterns or gotchas, append to `docs/critical-learnings.md`
-   - Commit all changes:
-     ```bash
-     git add -A
-     git commit -m "feat: [Task Group ID] - [Task Group Title]"
-     ```
-   - **STOP HERE** - Do NOT output the completion signal. The loop will automatically start the next iteration to find more task groups.
-
-5. **Quality Checks (Run Before Every Commit)**
-   First, read `package.json` to discover available scripts. Then run the relevant ones:
-   - If `typecheck` or `tsc` script exists: run it
-   - If `test` script exists: run it
-   - If `lint` script exists: run it
-   - If `build` script exists: run it to verify compilation
-
-   All checks must pass before committing. If a check fails, fix the issue and retry.
-
-   If you attempt to fix the same issue 3 times within this session without success, document the blocker in your Ralph log and mark the task as ⏸️ Blocked. Then move to the next task.
-
-## Logging
-
-Create verbose logs for each Ralph session. After completing a task group (or when blocked):
-
-1. Create or append to `docs/ralph_logs/YYYYMMDD_HHMM_ralph.md`:
-
-```markdown
-# Ralph Log: YYYY-MM-DD HH:MM
-
-## Task Group: [ID] - [Title]
-
-### Tasks Completed
-- [Task ID]: [Brief description of what was done]
-
-### Files Changed
-- `path/to/file.ts` - [what changed]
-
-### Quality Check Results
-- typecheck: ✅ passed / ❌ failed (details)
-- test: ✅ passed / ❌ failed (details)
-- lint: ✅ passed / ❌ failed (details)
-
-### Blockers (if any)
-- [Description of blocker and attempts made]
-
-### Learnings
-- [Patterns discovered, gotchas encountered]
-```
-
-2. Also update `docs/progress.md` with a brief entry:
-```markdown
-### YYYY-MM-DD HH:MM - [Task Group ID] (Ralph)
-- Summary of work done
-- See: ralph_logs/YYYYMMDD_HHMM_ralph.md
-```
-
-## Rules
-
-- Work on ONE task group per iteration
-- NEVER output the COMPLETE signal unless ALL tasks in ALL task groups are ✅ Complete
-- NEVER ask for human input - work autonomously
-- NEVER skip quality checks
-- If blocked after 3 attempts on the same issue, document it and move on
-- Commit after completing each task group, not after each individual task
-- Keep commits atomic and CI-friendly
-- After committing a task group, just STOP - the loop will automatically continue
-
-## Status Legend
-
-- 🔵 Planned - Not started
-- 🟡 In Progress - Currently being worked on
-- ✅ Complete - Done and verified
-- ⏸️ Blocked - Cannot proceed (document why in Ralph log)
-
-## Files to Read on Startup
-
-Before starting work, read these files to understand context:
-- `.flight-rules/AGENTS.md` - Framework guidelines
-- `docs/prd.md` - Project requirements
-- `docs/progress.md` - Recent work history (especially the last entry)
-- `docs/critical-learnings.md` - Patterns and gotchas to follow
-- `docs/implementation/overview.md` - Implementation structure
-- `package.json` - Available scripts for quality checks