flight-rules 0.5.9

package/payload/commands/test.add.md

@@ -0,0 +1,73 @@
+# Add Test
+
+When the user invokes this command, help them create a new test file following the project's testing conventions.
+
+## 1. Read Testing Context
+
+First, read `docs/tech-stack.md` to understand:
+- What testing framework is in use
+- Where test files should be located
+- Naming conventions for test files
+- Test structure patterns and conventions
+- Assertion and mocking approaches
+
+If `docs/tech-stack.md` doesn't exist or the Testing section is empty, run the `/test.assess-current` workflow first, or ask the user to describe their testing setup.
+
+## 2. Understand What to Test
+
+Ask the user:
+
+> "What would you like to test?"
+>
+> You can:
+> - Point me to a specific file or function
+> - Describe the behavior you want to test
+> - Ask me to suggest areas that need test coverage
+
+## 3. Analyze the Target
+
+Once the user specifies what to test:
+- Read the relevant source file(s)
+- Understand the function/component/module behavior
+- Identify key scenarios to test:
+  - Happy path
+  - Edge cases
+  - Error conditions
+  - Boundary conditions (if applicable)
+
+## 4. Propose Test Plan
+
+Before writing code, propose the test plan:
+
+> **Proposed Tests for [target]**
+>
+> I'll create `[test file path]` with the following test cases:
+>
+> 1. **[test name]** - [what it verifies]
+> 2. **[test name]** - [what it verifies]
+> 3. ...
+>
+> Does this look right, or would you like to adjust the scope?
+
+Wait for user confirmation before proceeding.
+
+## 5. Create the Test File
+
+Write the test file following the project's conventions from `docs/tech-stack.md`:
+- Use the correct file location and naming
+- Match the existing test structure style
+- Use the project's assertion library
+- Use the project's mocking approach if needed
+- Include appropriate imports
+
+## 6. Verify and Report
+
+After creating the test:
+
+> **Test created:** `[path to test file]`
+>
+> Run with: `[test command]`
+>
+> Would you like me to run the tests now to verify they pass?
+
+

package/payload/commands/test.assess-current.md

@@ -0,0 +1,75 @@
+# Assess Current Testing Setup
+
+When the user invokes this command, assess the project's testing environment and update `docs/tech-stack.md`.
+
+## 1. Scan for Test Configuration
+
+Look for test configuration files in the project root and common locations:
+
+**JavaScript/TypeScript:**
+- `vitest.config.ts`, `vitest.config.js`
+- `jest.config.ts`, `jest.config.js`, `jest.config.mjs`
+- `package.json` (check for `jest` or `vitest` config sections)
+
+**Python:**
+- `pytest.ini`, `pyproject.toml` (pytest section), `setup.cfg`
+- `tox.ini`
+
+**Other:**
+- `*.test.*`, `*_test.*`, `*_spec.*` file patterns
+- `tests/`, `test/`, `__tests__/`, `spec/` directories
+
+## 2. Analyze Test Files
+
+Examine existing test files to understand:
+- **Naming conventions**: How are test files named?
+- **Location pattern**: Co-located with source, or in separate directory?
+- **Test structure**: describe/it blocks, test classes, function-based?
+- **Assertion style**: expect(), assert, should
+- **Mocking approach**: What mocking utilities are used?
+
+## 3. Check for Test Scripts
+
+Examine `package.json` (or equivalent) for:
+- Test run commands
+- Watch mode commands
+- Coverage commands
+
+## 4. Update docs/tech-stack.md
+
+Update the **Testing** section of `docs/tech-stack.md` with your findings:
+- Framework name and version (if detectable)
+- Test location and naming conventions
+- Commands for running tests
+- Patterns and conventions observed
+- A representative example of test structure from the codebase
+
+If `docs/tech-stack.md` doesn't exist, create it using the template from `.flight-rules/doc-templates/tech-stack.md`.
+
+## 5. Report to User
+
+Present a summary to the user covering:
+
+> **Testing Assessment Complete**
+>
+> **Framework:** [detected framework]
+> **Test Location:** [where tests live]
+> **Run Command:** [how to run tests]
+>
+> **Observations:**
+> - [key observations about testing patterns]
+> - [any gaps or recommendations]
+>
+> I've updated `docs/tech-stack.md` with these findings.
+
+If no testing setup is detected, report:
+
+> **No Testing Setup Detected**
+>
+> I couldn't find a testing framework configured in this project.
+>
+> Would you like me to help you set up testing? If so, let me know:
+> 1. What language/framework is this project using?
+> 2. Do you have a preferred testing framework?
+
+

package/payload/doc-templates/critical-learnings.md

@@ -0,0 +1,21 @@
+# Critical Learnings
+
+A curated list of important insights, patterns, and decisions that should inform future work.
+
+---
+
+<!-- 
+Add learnings as they emerge from sessions:
+
+## Category Name
+
+### Learning Title
+
+**Context:** When/where this came up
+
+**Insight:** What we learned
+
+**Implication:** How this should affect future decisions
+-->
+
+

package/payload/doc-templates/implementation/overview.md

@@ -0,0 +1,27 @@
+# Implementation Overview
+
+This document lists the major implementation areas for this project.
+
+## Implementation Areas
+
+<!-- 
+Add implementation areas as you define them:
+
+1. **Area Name** – Brief description
+   - Status: 🔵 Planned / 🟡 In Progress / ✅ Complete
+   - See: `1-area-name/`
+
+2. **Another Area** – Brief description
+   - Status: 🔵 Planned
+   - See: `2-another-area/`
+-->
+
+## How to Use This
+
+1. Each numbered area has its own directory: `{N}-{kebab-topic}/`
+2. Inside each directory:
+   - `index.md` – Overview and goals for that area
+   - `{N}.{M}-topic.md` – Detailed specs for sub-areas
+3. Status is tracked in the detailed spec files, not here
+
+

package/payload/doc-templates/prd.md

@@ -0,0 +1,49 @@
+# Product Requirements Document
+
+<!-- 
+This template defines what you're building and why.
+Fill in each section; delete comments when done.
+-->
+
+## Overview
+
+<!-- 
+What is this project? Why does it exist?
+Describe the product/feature in 2-3 sentences.
+-->
+
+## Goals
+
+<!-- 
+What are the high-level goals this project aims to achieve?
+List 3-5 specific, measurable outcomes.
+-->
+
+## Non-Goals
+
+<!-- 
+What is explicitly out of scope?
+Listing non-goals prevents scope creep and clarifies focus.
+-->
+
+## User Stories
+
+<!-- 
+Who benefits from this, and how?
+Format: "As a [type of user], I want [goal] so that [benefit]."
+-->
+
+## Constraints
+
+<!-- 
+What limitations affect this project?
+Consider: timeline, budget, technology, dependencies, team capacity.
+-->
+
+## Success Criteria
+
+<!-- 
+How will you know this project succeeded?
+Define observable, measurable outcomes.
+-->
+

package/payload/doc-templates/progress.md

@@ -0,0 +1,19 @@
+# Progress
+
+A running log of sessions and milestones.
+
+---
+
+## Session Logs
+
+<!-- 
+Add session entries as you complete them:
+
+### YYYY-MM-DD HH:MM
+
+- What was accomplished
+- Key decisions made
+- See: [session_logs/YYYYMMDD_HHMM_session.md](session_logs/YYYYMMDD_HHMM_session.md)
+-->
+
+

package/payload/doc-templates/session-log.md

@@ -0,0 +1,62 @@
+# Session Log: YYYY-MM-DD HH:MM
+
+<!-- 
+Template for coding session documentation.
+Agents create new session logs in docs/session_logs/ following this structure.
+Naming convention: YYYYMMDD_HHMM_session.md
+-->
+
+## Session Goals
+
+<!-- What did we set out to accomplish? -->
+
+- Goal 1
+- Goal 2
+
+## Related Specs
+
+<!-- Which Task Groups and Tasks does this session address? -->
+
+- Task Group: `X.Y-topic.md`
+- Tasks: X.Y.1, X.Y.2
+
+## Summary
+
+<!-- Brief overview of what was accomplished -->
+
+## Implementation Details
+
+<!-- Notable technical choices, patterns used, architecture decisions -->
+
+## Key Decisions
+
+<!-- Important decisions made during this session, especially any deviations from the original plan -->
+
+## Challenges & Solutions
+
+<!-- Problems encountered and how they were resolved -->
+
+## Code Areas Touched
+
+<!-- List of files/directories modified -->
+
+- `path/to/file.ts`
+
+## Spec Updates Needed
+
+<!-- Any spec files that need to be updated based on what was actually implemented -->
+
+- [ ] Update `X.Y-topic.md` Task X.Y.1 status to ✅ Complete
+
+## Next Steps
+
+<!-- What should happen in future sessions? -->
+
+- Next step 1
+- Next step 2
+
+## Learnings
+
+<!-- Insights worth promoting to critical-learnings.md -->
+
+

package/payload/doc-templates/tech-stack.md

@@ -0,0 +1,101 @@
+# Tech Stack
+
+This document describes the technical environment for this project. It serves as a reference for humans and agents when performing tech-dependent tasks.
+
+---
+
+## Testing
+
+<!-- 
+This section is the primary focus. Document your testing setup so that agents
+can create appropriate tests without requiring you to re-explain the framework.
+
+Use the `/test.assess-current` command to auto-populate this section.
+-->
+
+### Framework
+
+<!-- 
+What testing framework does this project use?
+Examples: Vitest, Jest, pytest, RSpec, Go testing, etc.
+-->
+
+### Test Location & Naming
+
+<!-- 
+Where do test files live? What naming conventions are used?
+
+Examples:
+- Tests live in `tests/` directory, mirroring `src/` structure
+- Test files named `*.test.ts` or `*.spec.ts`
+- Co-located with source files as `ComponentName.test.tsx`
+-->
+
+### Running Tests
+
+<!-- 
+What commands are used to run tests?
+
+Examples:
+- `npm test` - Run all tests
+- `npm run test:watch` - Watch mode
+- `npm run test:coverage` - With coverage report
+-->
+
+### Patterns & Conventions
+
+<!-- 
+What patterns does this project follow for writing tests?
+
+Consider documenting:
+- Assertion style (expect, assert, should)
+- Mocking approach (vi.mock, jest.mock, unittest.mock)
+- Test organization (describe/it blocks, test classes)
+- Fixtures or factories used
+- Any custom test utilities
+-->
+
+### Example Test Structure
+
+<!-- 
+Provide a representative example of how tests are structured in this project.
+This helps agents match the existing style.
+
+```typescript
+// Example test structure goes here
+```
+-->
+
+---
+
+## Runtime & Language
+
+<!-- 
+Brief notes on the runtime environment.
+Examples: Node.js 20, Python 3.11, Go 1.21
+-->
+
+---
+
+## Build Tools
+
+<!-- 
+Brief notes on build/bundling tools if relevant.
+Examples: TypeScript + tsup, Vite, webpack, esbuild
+-->
+
+---
+
+## Key Dependencies
+
+<!-- 
+List major frameworks or libraries that define the project's architecture.
+Not an exhaustive list—just the ones that matter for understanding the codebase.
+
+Examples:
+- React 18 with React Router
+- Express.js for API
+- Prisma for database access
+-->
+
+

package/payload/prompts/implementation/README.md

@@ -0,0 +1,26 @@
+# Implementation Prompts
+
+Prompts to help create and review implementation plans.
+
+## Available Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `plan-review.md` | Critical review of an implementation plan by a second agent |
+
+## Usage
+
+Copy the prompt into your AI assistant, specifying which part of the implementation plan to review. The AI will read the relevant docs from `docs/implementation/` and provide structured feedback.
+
+## Workflow
+
+A typical workflow for using these prompts:
+
+1. **Agent 1** creates an implementation plan (Area, Task Group, or Task specs)
+2. **You** open a new session with **Agent 2** and paste the review prompt
+3. **You** specify what to review (e.g., "Area 2", "Task Group 2.3", "Task 2.3.4")
+4. **Agent 2** reads the implementation docs and provides critical feedback
+5. **You** incorporate feedback and finalize the plan
+
+This "two-agent review" pattern helps catch gaps, assumptions, and issues before implementation begins.
+

package/payload/prompts/implementation/plan-review.md

@@ -0,0 +1,80 @@
+# Implementation Plan Review — Prompt
+
+Use this prompt to have an AI assistant critically review an implementation plan created by another agent (or yourself).
+
+---
+
+## The Prompt
+
+Copy everything below the line into your AI assistant:
+
+---
+
+You are a senior software architect and technical lead with deep experience shipping production systems. You're known for catching issues early, asking hard questions, and improving plans before a single line of code is written. Your job is to critically review part of this project's implementation plan.
+
+**What to review:**
+
+Review the following from `docs/implementation/`:
+
+> **[SPECIFY WHAT TO REVIEW — examples below]**
+> - `2-feature-name/` — review the entire Area
+> - `2.3-task-group.md` — review a specific Task Group
+> - `2.3.4` — review a specific Task within a Task Group
+> - "All tasks marked 🔵 Planned in Area 2" — review by status
+
+Read the specified implementation docs now before proceeding with your review.
+
+**Your review philosophy:**
+
+The goal is a *good enough* plan, not a perfect one. Implementation plans are guides, not scripts — some details are better discovered during coding. Resist the urge to add endless clarifications.
+
+Ask yourself: "Could a competent developer proceed with this?" If yes, it's probably fine. Don't flag something just because it *could* be more detailed.
+
+**What to look for:**
+
+- Genuine blockers — things that would cause implementation to fail or go badly wrong
+- Missing pieces that would force the developer to stop and ask questions
+- Risks that aren't acknowledged
+- Scope that doesn't match the stated goals
+
+**What NOT to flag:**
+
+- Stylistic preferences or "I would have written it differently"
+- Details that are obvious to any experienced developer
+- Edge cases that can be handled when encountered
+- Optimizations that aren't relevant yet
+
+**Review dimensions** (scan for issues, don't exhaustively analyze each):
+
+1. **Can a developer proceed?** — Is it clear what to build and roughly how?
+2. **Will it work?** — Are there technical red flags or missing dependencies?
+3. **Does it match the goals?** — Is there scope creep or missing scope?
+4. **What's the biggest risk?** — What's most likely to go wrong?
+
+**Your output format:**
+
+Organize your feedback as follows:
+
+1. **Summary** — A 2-3 sentence overall assessment. End with a clear verdict: "Ready to implement", "Needs minor fixes", or "Needs rework"
+
+2. **Critical Issues** (max 3) — True blockers only. These are problems that would cause implementation to fail or go seriously wrong. If there are no blockers, say "None" — don't invent issues to fill this section.
+
+3. **Suggestions** (max 5) — Non-blocking improvements, ranked by impact. These are "would be better if" items, not "must fix" items.
+
+4. **Questions** (if any) — Only include questions that would change your assessment. Skip this section if you have none.
+
+**Important constraints:**
+
+- If you find yourself listing more than 3 critical issues, you're probably being too strict. Re-evaluate what's truly a blocker.
+- Suggestions beyond the top 5 aren't worth the iteration time. Be ruthless about what matters.
+- "This could be clearer" is not a critical issue unless a developer literally couldn't proceed.
+- Don't suggest adding detail just because you could imagine more detail existing.
+
+**Tone guidance:**
+
+- Be direct but constructive — the goal is a better plan, not criticism for its own sake
+- If the plan is good, say so briefly and move on — don't pad your review
+- When you identify an issue, suggest a fix, not just the problem
+
+**Now read the specified implementation docs and provide your review.**
+

package/payload/prompts/prd/README.md

@@ -0,0 +1,46 @@
+# PRD Prompts
+
+Prompts and commands to help create Product Requirements Documents.
+
+## Recommended: Use Commands
+
+The preferred way to create and refine PRDs is through the commands in `.flight-rules/commands/`:
+
+| Command | Description |
+|---------|-------------|
+| `/prd.create` | Create a new PRD (supports conversational interview or one-shot from description) |
+| `/prd.clarify` | Refine specific sections of an existing PRD |
+
+These commands integrate better with the Flight Rules workflow and automatically save output to `docs/prd.md`.
+
+## Available Prompts
+
+These standalone prompts can be copied into any AI assistant:
+
+| Prompt | Description |
+|--------|-------------|
+| `creation-conversational.md` | Interactive interview that walks through each PRD section |
+
+**Note:** The `creation-conversational.md` prompt is the foundation for the `/prd.create` command's conversational mode. Use the command for better workflow integration, or use the prompt directly if you prefer a standalone conversation.
+
+## Usage
+
+**With commands (recommended):**
+- Invoke `/prd.create` to start creating a PRD
+- Invoke `/prd.clarify` to refine specific sections
+
+**With prompts:**
+- Copy the prompt into your AI assistant and follow the conversation
+- The template for the PRD is at `.flight-rules/doc-templates/prd.md`
+- After completing the conversation, save the output to `docs/prd.md`
+
+## Output
+
+Both commands and prompts produce a completed PRD that follows the standard template structure:
+
+- Overview
+- Goals
+- Non-Goals
+- User Stories
+- Constraints
+- Success Criteria

package/payload/prompts/prd/creation-conversational.md

@@ -0,0 +1,46 @@
+# PRD Creation — Conversational Prompt
+
+Use this prompt to have an AI assistant interview you and help create a Product Requirements Document.
+
+---
+
+## The Prompt
+
+Copy everything below the line into your AI assistant:
+
+---
+
+You are a senior product manager who has shipped multiple successful products. You're known for asking "why" until you truly understand the problem, and for pushing back when requirements are vague or unmeasurable. Your job is to interview me and help create a Product Requirements Document (PRD).
+
+**How this works:**
+
+1. You'll ask me about one section at a time
+2. Ask 1-2 questions per section, with follow-ups if my answers need clarification
+3. Summarize what you heard before moving to the next section
+4. At the end, review for consistency and generate the complete PRD
+
+**The PRD has 6 sections:**
+
+1. Overview — What is this project? Why does it exist?
+2. Goals — What are we trying to achieve?
+3. Non-Goals — What is explicitly out of scope?
+4. User Stories — Who benefits and how?
+5. Constraints — What limitations affect this project?
+6. Success Criteria — How will we know it worked?
+
+**Your approach:**
+
+- Push back when I'm vague — don't just accept my first answer
+- Ask "why" and "how will you measure that" frequently
+- If I say "I don't know," help me figure it out rather than moving on
+- Don't let me skip Non-Goals — people always forget these and regret it later
+- Challenge goals that sound like platitudes ("improve user experience" is not a goal)
+- Insist that success criteria be specific and measurable
+
+**Before generating the final PRD:**
+
+- Check that goals and non-goals don't conflict
+- Verify every success criterion is actually measurable
+- Flag anything that feels incomplete or hand-wavy
+
+**Start now.** Introduce yourself briefly, then begin with the Overview section.