flight-rules 0.5.9

package/payload/commands/dev-session.start.md

@@ -0,0 +1,54 @@
+# Start Coding Session
+
+When the user invokes "start coding session", follow this process:
+
+## 1. Review Project Context
+
+Read and understand:
+- `docs/prd.md` – What is this project?
+- `docs/implementation/overview.md` – What are the implementation areas?
+- `docs/progress.md` – What was done recently?
+- The most recent `docs/session_logs/*_session.md` – What happened last session?
+
+Scan relevant code as needed to understand current state.
+
+## 2. Establish Session Goals
+
+Ask the user:
+> "What would you like to accomplish in this session?"
+
+Also suggest goals based on:
+- "Next Steps" from the last session
+- Spec items with status 🔵 Planned or 🟡 In Progress
+
+Agree on a small set of specific, achievable goals (typically 1-3).
+
+## 3. Create Implementation Plan
+
+Collaborate with the user on:
+- **Technical approach** – How will we implement this?
+- **Alternatives considered** – What other options exist?
+- **Constraints** – What limitations should we keep in mind?
+- **Potential challenges** – What might go wrong and how will we handle it?
+
+## 4. Document the Session Plan
+
+Create a new file: `docs/session_logs/YYYYMMDD_HHMM_session.md`
+
+Use the template at `.flight-rules/doc-templates/session-log.md` as a guide.
+
+Include:
+- Session goals
+- Related Task Groups and Tasks (by ID)
+- Technical approach
+- Task breakdown
+
+## 5. Confirm Before Coding
+
+Present the plan to the user and ask:
+
+> "The session plan has been documented in `docs/session_logs/YYYYMMDD_HHMM_session.md`. Are you ready for me to begin implementing this plan?"
+
+**Do not begin implementation until the user confirms.**
+
+

package/payload/commands/impl.create.md

@@ -0,0 +1,178 @@
+# Create Implementation Detail
+
+When the user invokes "impl.create", add detailed task groups and tasks to the implementation specs.
+
+This command works at different scopes:
+- **Full project** – Detail all areas (for smaller projects)
+- **One area** – Detail a specific area's task groups
+- **One task group** – Add tasks to a specific task group
+
+## 1. Determine Scope
+
+Check if the user provided a scope argument:
+- `/impl.create` → Ask what scope they want
+- `/impl.create 1-authentication` → Detail that area
+- `/impl.create 1.2` → Detail that task group
+
+If no argument provided, ask:
+> "What would you like to detail?
+> 1. **Full project** – Create detailed specs for all areas
+> 2. **One area** – Pick an area to flesh out (e.g., `1-authentication`)
+> 3. **One task group** – Add detail to a specific task group (e.g., `1.2`)
+>
+> Which scope, or enter an area/task group identifier?"
+
+## 2. Verify Prerequisites
+
+### For full project or area scope:
+- Check `docs/implementation/overview.md` exists
+- If not, suggest running `/impl.outline` first
+
+### For task group scope:
+- Check the parent area exists
+- If not, suggest creating the area first
+
+### Always:
+- Read `docs/prd.md` for context on goals and constraints
+- Scan relevant existing code to understand what's already built
+
+## 3. Propose the Detail
+
+Based on scope, propose task groups and/or tasks:
+
+### For Area Scope
+
+Propose task groups within the area:
+
+```
+Detailing Area: 1. Authentication
+
+Proposed Task Groups:
+
+1.1 **User Registration** – Account creation flow
+    - Email validation, password requirements, confirmation
+
+1.2 **Login/Logout** – Session management
+    - Credential verification, session tokens, logout cleanup
+
+1.3 **Password Reset** – Recovery flow
+    - Reset requests, email tokens, password update
+
+Does this breakdown make sense? Would you like to adjust before I create the specs?
+```
+
+### For Task Group Scope
+
+Propose tasks within the task group:
+
+```
+Detailing Task Group: 1.2 Login/Logout
+
+Proposed Tasks:
+
+1.2.1 **Login Form UI** – Create the login interface
+1.2.2 **Credential Verification** – Backend auth logic
+1.2.3 **Session Token Management** – Create and validate tokens
+1.2.4 **Logout Flow** – Clear session and redirect
+
+Does this breakdown make sense?
+```
+
+### For Full Project Scope
+
+Show the complete structure across all areas, then confirm.
+
+**Do not create files until the user confirms.**
+
+## 4. Create the Spec Files
+
+Once approved, create or update:
+
+### Task Group Files
+
+For each task group, create `docs/implementation/{N}-{area}/{N}.{M}-topic.md`:
+
+```markdown
+# {N}.{M} Task Group Name
+
+Brief description of what this task group covers and why it matters.
+
+## Goals
+- What this task group accomplishes
+- How it maps to PRD goals
+
+## Constraints
+- Technical limitations or requirements
+- Dependencies on other task groups (if any)
+
+## Dependencies
+- **Requires**: List any task groups that must be completed first
+- **Enables**: List any task groups that depend on this one
+
+---
+
+## {N}.{M}.1. First Task Name
+
+**Goal**: What this specific task accomplishes
+
+**Approach**: High-level technical approach (2-3 sentences)
+
+**Acceptance Criteria**:
+- Specific, testable criteria
+- What "done" looks like
+
+**Status**: 🔵 Planned
+
+---
+
+## {N}.{M}.2. Second Task Name
+
+**Goal**: ...
+
+**Approach**: ...
+
+**Acceptance Criteria**:
+- ...
+
+**Status**: 🔵 Planned
+```
+
+### Update Area Index
+
+Update `docs/implementation/{N}-{area}/index.md` to list the task groups:
+
+```markdown
+## Task Groups
+
+- **[1.1 User Registration](./1.1-user-registration.md)** – Account creation flow
+- **[1.2 Login/Logout](./1.2-login-logout.md)** – Session management
+- ...
+```
+
+### Update Overview (if needed)
+
+Update area status in `docs/implementation/overview.md` if moving from planned to detailed.
+
+## 5. Summarize What Was Created
+
+After creating files, present:
+- List of files created/updated
+- Total number of tasks defined
+- Suggested starting point
+- Any noted dependencies
+
+Ask:
+> "The specs have been created. Would you like to:
+> - Start a coding session with `/dev-session.start`?
+> - Detail another area with `/impl.create {area}`?
+> - Review and adjust any of the specs?"
+
+## Guidelines
+
+- **Right-size tasks** – Each task should be roughly one focused coding session
+- **Clear acceptance criteria** – Every task needs testable "done" conditions
+- **Note dependencies** – If Task B requires Task A, document it explicitly
+- **Map to PRD** – Reference which PRD goals each task group supports
+- **Start simple** – Placeholder descriptions are fine; they'll be refined during sessions
+- **All tasks start 🔵 Planned** – Status updates happen during `/dev-session.start` and `/dev-session.end`
+- **Respect existing work** – If specs already exist for a scope, ask before overwriting

package/payload/commands/impl.outline.md

@@ -0,0 +1,120 @@
+# Create Implementation Outline
+
+When the user invokes "impl.outline", create a high-level implementation structure from the PRD.
+
+This command creates the skeleton — areas and their brief descriptions — without detailed tasks. Use `/impl.create` afterward to add detail to specific areas.
+
+## 1. Review the PRD
+
+Read `docs/prd.md` thoroughly. Understand:
+- **Overview** – What problem are we solving?
+- **Goals** – What are the measurable outcomes?
+- **Non-Goals** – What's explicitly out of scope?
+- **User Stories** – Who benefits and how?
+- **Constraints** – What limitations apply?
+
+If no PRD exists, stop and suggest running `/prd.create` first.
+
+## 2. Scan Existing Structure
+
+Check what already exists:
+- `docs/implementation/overview.md` – Is there an existing outline?
+- `docs/implementation/*/` – Any existing area directories?
+- Codebase structure – What patterns exist?
+
+If an outline already exists, ask:
+> "An implementation outline already exists. Would you like me to revise it, or extend it with additional areas?"
+
+## 3. Propose Areas
+
+Design 3-7 major implementation areas that map to PRD goals. Consider:
+- **Logical grouping** – Related functionality together
+- **Dependencies** – Lower numbers = foundational, higher = builds on earlier
+- **Scope** – Each area should be substantial but not overwhelming
+
+Present the proposed structure:
+
+```
+Proposed Implementation Areas:
+
+1. **Area Name** – Brief description (1-2 sentences)
+   Maps to PRD goals: [list relevant goals]
+
+2. **Another Area** – Brief description
+   Maps to PRD goals: [list relevant goals]
+
+3. ...
+```
+
+Ask:
+> "Does this breakdown make sense? Would you like to add, remove, or reorganize any areas before I create the structure?"
+
+**Do not create files until the user confirms.**
+
+## 4. Create the Skeleton
+
+Once approved, create:
+
+### Overview File
+
+Create or update `docs/implementation/overview.md`:
+
+```markdown
+# Implementation Overview
+
+This document lists the major implementation areas for this project.
+
+## Implementation Areas
+
+1. **Area Name** – Brief description
+   - Status: 🔵 Planned
+   - See: `1-area-name/`
+
+2. **Another Area** – Brief description
+   - Status: 🔵 Planned
+   - See: `2-another-area/`
+
+...
+```
+
+### Area Directories
+
+For each area, create:
+- Directory: `docs/implementation/{N}-{kebab-name}/`
+- Index file: `docs/implementation/{N}-{kebab-name}/index.md`
+
+Index file template:
+```markdown
+# {N}. Area Name
+
+Brief description of this area and what it accomplishes.
+
+## Goals
+- What this area achieves
+- How it relates to PRD goals
+
+## Key Considerations
+- Important constraints or decisions
+- Dependencies on other areas
+
+## Task Groups
+
+_Task groups will be defined when this area is detailed. Run `/impl.create {N}-{area-name}` to add detail._
+```
+
+## 5. Summarize and Suggest Next Steps
+
+After creating files, present:
+- List of files created
+- Suggested order for detailing areas (based on dependencies)
+
+Ask:
+> "The implementation outline has been created. Which area would you like to detail first? You can run `/impl.create {area}` to add task groups and tasks."
+
+## Guidelines
+
+- **Keep it high-level** – Don't try to detail tasks yet; that's what `/impl.create` is for
+- **Map to PRD goals** – Every area should trace back to at least one PRD goal
+- **Respect non-goals** – Don't create areas for out-of-scope work
+- **Consider dependencies** – Number areas so foundational work comes first
+- **3-7 areas is ideal** – Fewer than 3 suggests the project is simple; more than 7 suggests areas should be consolidated

package/payload/commands/prd.clarify.md

@@ -0,0 +1,139 @@
+# Clarify PRD
+
+When the user invokes this command, help them refine specific sections of an existing Product Requirements Document (PRD).
+
+## 1. Read Existing PRD
+
+Read `docs/prd.md`. If it doesn't exist or is empty:
+
+> "I couldn't find an existing PRD at `docs/prd.md`. Would you like me to create one first with `/prd.create`?"
+
+Stop and wait for the user's response.
+
+## 2. Identify Sections to Clarify
+
+If the user specified a section with the command (e.g., "clarify the Goals section"), proceed to clarify that section.
+
+Otherwise, present the current PRD structure and ask:
+
+> **Current PRD Structure:**
+>
+> 1. **Overview** — [brief summary or "minimal content"]
+> 2. **Goals** — [count of goals or "minimal content"]
+> 3. **Non-Goals** — [count of non-goals or "minimal content"]
+> 4. **User Stories** — [count of stories or "minimal content"]
+> 5. **Constraints** — [count of constraints or "minimal content"]
+> 6. **Success Criteria** — [count of criteria or "minimal content"]
+>
+> Which section(s) would you like to clarify?
+
+Wait for the user to specify which section(s) to work on.
+
+## 3. Clarify Each Section
+
+For each section the user wants to clarify, follow this process:
+
+### 3.1 Summarize Current Content
+
+> **Current [Section Name]:**
+>
+> [Quote or summarize the current content]
+
+### 3.2 Ask Targeted Questions
+
+Ask 1-2 specific questions to draw out more detail. Tailor questions to the section:
+
+**Overview:**
+- "What specific problem does this solve for users?"
+- "Why is this the right time to build this?"
+
+**Goals:**
+- "How will you measure [specific goal]?"
+- "What does success look like for [goal] — can you put a number on it?"
+- "Is [goal] achievable in your timeline, or should it be scoped differently?"
+
+**Non-Goals:**
+- "I noticed [feature/scope] wasn't mentioned in goals. Is that intentionally out of scope?"
+- "Are there adjacent problems you're explicitly not solving in v1?"
+- "What requests might stakeholders make that you'll need to say no to?"
+
+**User Stories:**
+- "Are there other user types who would benefit from this?"
+- "What's the most important thing [user type] needs to accomplish?"
+- "What would make [user type] frustrated with this solution?"
+
+**Constraints:**
+- "Are there technology choices that are fixed vs. flexible?"
+- "What's the timeline, and is it firm or negotiable?"
+- "Are there dependencies on other teams or systems?"
+
+**Success Criteria:**
+- "How will you actually measure [criterion]? What data do you have access to?"
+- "What's the threshold for success vs. failure?"
+- "When will you evaluate this — at launch, 30 days, 90 days?"
+
+### 3.3 Push Back on Vagueness
+
+If the user's answers are vague or unmeasurable, push back:
+
+- ❌ "Improve user experience" → ✅ "Reduce task completion time by 20%"
+- ❌ "Make it faster" → ✅ "Page load under 2 seconds on 3G connections"
+- ❌ "Users will like it" → ✅ "NPS score of 40+ within 90 days"
+
+> "That's a good direction, but it's hard to measure. How would you know if you've achieved [vague goal]? What would you observe or measure?"
+
+### 3.4 Check for Conflicts
+
+As you clarify, watch for conflicts with other sections:
+
+- Goals that contradict non-goals
+- Success criteria that don't align with goals
+- Constraints that make goals unachievable
+- User stories that suggest goals not listed
+
+If you spot a conflict:
+
+> "I noticed a potential conflict: [describe conflict]. Should we adjust one of these?"
+
+### 3.5 Propose Updated Content
+
+After gathering more detail, propose the updated section:
+
+> **Proposed [Section Name]:**
+>
+> [Show the proposed updated content]
+>
+> Does this capture what we discussed, or would you like to adjust it?
+
+Wait for user approval before proceeding.
+
+## 4. Update the PRD
+
+After the user approves the clarified sections:
+
+1. Update `docs/prd.md` with the new content
+2. Preserve sections that weren't modified
+
+## 5. Report Changes
+
+Summarize what was changed:
+
+> **PRD Updated:** `docs/prd.md`
+>
+> **Sections clarified:**
+> - [Section 1]: [brief description of changes]
+> - [Section 2]: [brief description of changes]
+>
+> Would you like to clarify any other sections?
+
+## Key Behaviors
+
+Throughout this command, maintain these behaviors:
+
+- **Be specific in questions** — Ask about concrete details, not abstract concepts
+- **Push back on vagueness** — Measurable > aspirational
+- **Watch for conflicts** — Sections should be internally consistent
+- **Propose, don't impose** — Show proposed changes and wait for approval
+- **One section at a time** — Don't overwhelm with too many changes at once
+
+

package/payload/commands/prd.create.md

@@ -0,0 +1,154 @@
+# Create PRD
+
+When the user invokes this command, help them create a Product Requirements Document (PRD). This command supports two modes: conversational (default) and one-shot (when the user provides a description).
+
+## 1. Check for Existing PRD
+
+Read `docs/prd.md` if it exists. If it contains substantive content (not just the template):
+
+> "I found an existing PRD at `docs/prd.md`. Would you like me to:"
+> 1. **Replace it** — Start fresh with a new PRD
+> 2. **Refine it** — Use `/prd.clarify` to improve specific sections
+>
+> Which would you prefer?
+
+Wait for the user's response before proceeding.
+
+## 2. Determine Mode
+
+**One-shot mode:** If the user provided a description with the command (e.g., "create a PRD for a photo organization app"), proceed to Step 3.
+
+**Conversational mode:** If the user invoked the command without a description, proceed to Step 4.
+
+## 3. One-Shot Mode
+
+Generate an initial PRD draft based on the user's description:
+
+1. Parse the description for key information about:
+   - What the product/feature is
+   - Who it's for
+   - What problem it solves
+
+2. Generate a draft PRD following the template structure from `.flight-rules/doc-templates/prd.md`:
+   - **Overview** — Synthesize the core concept
+   - **Goals** — Infer 3-5 measurable goals
+   - **Non-Goals** — Infer reasonable boundaries
+   - **User Stories** — Generate stories in "As a [user], I want [goal] so that [benefit]" format
+   - **Constraints** — Note any mentioned limitations
+   - **Success Criteria** — Propose measurable outcomes
+
+3. Present the draft with highlighted gaps:
+
+> **Draft PRD Generated**
+>
+> I've created an initial PRD based on your description. Here it is:
+>
+> [Show the complete draft]
+>
+> **Areas that may need more detail:**
+> - [List sections that seem thin or assumed]
+>
+> Would you like me to:
+> 1. Save this draft and refine specific sections
+> 2. Walk through each section conversationally to fill in gaps
+> 3. Save as-is
+
+4. Based on the user's choice:
+   - Option 1: Save to `docs/prd.md` and offer to run `/prd.clarify`
+   - Option 2: Switch to conversational mode (Step 4), using the draft as a starting point
+   - Option 3: Save to `docs/prd.md` and report completion
+
+## 4. Conversational Mode
+
+Adopt the persona of 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.
+
+### 4.1 Introduction
+
+> "I'm going to help you create a Product Requirements Document. I'll walk you through 6 sections, asking questions and pushing back when things are unclear. At the end, we'll have a complete PRD.
+>
+> Let's start with the **Overview**. What is this project, and why does it exist?"
+
+### 4.2 Interview Through Each Section
+
+Walk through each section one at a time:
+
+**Section 1: Overview**
+- Ask: What is this project? Why does it exist?
+- Push for clarity on the core problem being solved
+- Summarize before moving on
+
+**Section 2: Goals**
+- Ask: What are you trying to achieve? (aim for 3-5 goals)
+- Challenge platitudes ("improve user experience" → "reduce time to complete X by Y%")
+- Ask "how will you measure that?" for each goal
+- Summarize before moving on
+
+**Section 3: Non-Goals**
+- Ask: What is explicitly out of scope?
+- Don't let them skip this — people always forget and regret it
+- Suggest non-goals based on what you've heard (e.g., "It sounds like mobile support might be a non-goal for v1?")
+- Summarize before moving on
+
+**Section 4: User Stories**
+- Ask: Who benefits from this, and how?
+- Guide toward the format: "As a [type of user], I want [goal] so that [benefit]"
+- Push for multiple user types if appropriate
+- Summarize before moving on
+
+**Section 5: Constraints**
+- Ask: What limitations affect this project?
+- Prompt with categories: timeline, budget, technology, dependencies, team capacity
+- Summarize before moving on
+
+**Section 6: Success Criteria**
+- Ask: How will you know this project succeeded?
+- Insist on specific, measurable, observable outcomes
+- Connect back to Goals — every goal should have a way to measure success
+- Summarize before moving on
+
+### 4.3 Review and Validate
+
+Before generating the final PRD:
+
+1. **Check consistency:**
+   - Do goals and non-goals conflict?
+   - Are success criteria aligned with goals?
+   - Are user stories coherent with the overview?
+
+2. **Flag issues:**
+
+> **Before I generate the PRD, I noticed:**
+> - [List any inconsistencies or gaps]
+>
+> Would you like to address these, or proceed as-is?
+
+3. **Generate the complete PRD** following the template structure
+
+## 5. Save and Report
+
+Save the PRD to `docs/prd.md` and confirm:
+
+> **PRD Created:** `docs/prd.md`
+>
+> **Summary:**
+> - Overview: [one-line summary]
+> - Goals: [count] goals defined
+> - Non-Goals: [count] non-goals defined
+> - User Stories: [count] user stories
+> - Constraints: [count] constraints noted
+> - Success Criteria: [count] measurable criteria
+>
+> You can refine specific sections later with `/prd.clarify`.
+
+## Key Behaviors
+
+Throughout this command, maintain these behaviors:
+
+- **Push back on vagueness** — Don't accept first answers that are unclear
+- **Ask "why" repeatedly** — Until the real problem is understood
+- **Demand measurability** — Goals and success criteria must be specific
+- **Enforce non-goals** — These prevent scope creep
+- **Check consistency** — Goals, non-goals, and success criteria should align
+- **Help, don't block** — If user says "I don't know," help them figure it out
+
+