flight-rules 0.5.9 → 0.9.0

package/README.md

@@ -89,6 +89,28 @@ Two core flows:
 
 Agents don't start these flows on their own; you explicitly invoke them.
 
+### Available Commands
+
+Flight Rules provides workflow commands that agents can execute:
+
+| Command | Purpose |
+|---------|---------|
+| `/dev-session.start` | Begin a structured coding session with goals and plan |
+| `/dev-session.end` | End session, summarize work, update progress |
+| `/prd.create` | Create a Product Requirements Document |
+| `/prd.clarify` | Refine specific sections of an existing PRD |
+| `/impl.outline` | Create implementation area structure |
+| `/impl.create` | Add detailed tasks to implementation specs |
+| `/feature.add` | Add a new feature to PRD and implementation docs |
+| `/test.add` | Add tests for specific functionality |
+| `/test.assess-current` | Analyze existing test coverage |
+| `/prompt.refine` | Iteratively improve a prompt |
+| `/readme.create` | Generate README from PRD and project state |
+| `/readme.reconcile` | Update README to reflect recent changes |
+| `/prd.reconcile` | Update PRD based on what was actually built |
+| `/impl.reconcile` | Update implementation docs with status changes |
+| `/docs.reconcile` | Run all reconcile commands + consistency check |
+
 ### Versioning
 
 Each project tracks which Flight Rules version it uses:
@@ -126,11 +148,22 @@ your-project/
     │   ├── session-log.md
     │   └── implementation/
     │       └── overview.md
-    ├── commands/
+    ├── commands/             # Workflow commands
     │   ├── dev-session.start.md
     │   ├── dev-session.end.md
+    │   ├── prd.create.md
+    │   ├── prd.clarify.md
+    │   ├── impl.outline.md
+    │   ├── impl.create.md
+    │   ├── feature.add.md
     │   ├── test.add.md
-    │   └── test.assess-current.md
+    │   ├── test.assess-current.md
+    │   ├── prompt.refine.md
+    │   ├── readme.create.md
+    │   ├── readme.reconcile.md
+    │   ├── prd.reconcile.md
+    │   ├── impl.reconcile.md
+    │   └── docs.reconcile.md
     └── prompts/              # Reusable prompt templates
 ```
 

package/package.json

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

package/payload/commands/docs.reconcile.md

@@ -0,0 +1,242 @@
+# Reconcile All Documentation
+
+When the user invokes "docs.reconcile", run all reconciliation commands in sequence and then perform a cross-document consistency check.
+
+Adopt the persona of a documentation auditor who ensures all project docs tell a consistent story. You orchestrate the individual reconcile commands and then analyze the entire documentation set for internal consistency.
+
+## 1. Determine Scope
+
+### One-shot mode with explicit scope:
+
+If the user provided a scope argument, it applies to all reconcile commands:
+- `/docs.reconcile since v0.5.0`
+- `/docs.reconcile last 10 commits`
+- `/docs.reconcile since 2026-01-15`
+- `/docs.reconcile check-only` — Skip reconciliation, only run cross-check
+
+### Default scope detection:
+
+If no scope provided:
+
+1. Read `docs/progress.md` to find the last documented session
+2. Extract the date from the most recent session log entry
+3. Find commits since that date
+
+Present the detected scope:
+
+> "I found your last documented session was on [date]. I'll analyze the [N] commits since then across all documentation.
+>
+> This will run:
+> 1. `/readme.reconcile` — Update README
+> 2. `/prd.reconcile` — Update PRD
+> 3. `/impl.reconcile` — Update implementation docs
+> 4. **Cross-check** — Verify consistency across all docs
+>
+> Does this scope look right, or would you like to adjust it?"
+
+### Check-only mode:
+
+If user specified `check-only`:
+
+> "Running consistency check only (no reconciliation).
+>
+> I'll analyze README, PRD, and implementation docs for internal consistency without looking at git history."
+
+Skip to Step 5 (Cross-Check).
+
+## 2. Run README Reconcile
+
+Execute the `/readme.reconcile` workflow with the determined scope.
+
+After completion, summarize:
+
+> **README Reconciliation Complete**
+> - [Summary of changes made or "No changes needed"]
+>
+> Proceeding to PRD reconciliation...
+
+## 3. Run PRD Reconcile
+
+Execute the `/prd.reconcile` workflow with the determined scope.
+
+After completion, summarize:
+
+> **PRD Reconciliation Complete**
+> - [Summary of changes made or "No changes needed"]
+>
+> Proceeding to implementation docs reconciliation...
+
+## 4. Run Implementation Reconcile
+
+Execute the `/impl.reconcile` workflow with the determined scope.
+
+After completion, summarize:
+
+> **Implementation Docs Reconciliation Complete**
+> - [Summary of changes made or "No changes needed"]
+>
+> Proceeding to cross-document consistency check...
+
+## 5. Cross-Document Consistency Check
+
+Read all documentation files and analyze for consistency:
+
+### 5.1 README ↔ PRD Consistency
+
+Check:
+- Features mentioned in README exist as PRD goals
+- PRD overview matches README overview
+- Installation/usage in README matches constraints in PRD
+
+Flag inconsistencies:
+- README mentions feature X, but PRD has no corresponding goal
+- PRD goal Y is marked complete, but README doesn't mention it
+- README claims capability Z, but PRD lists it as a non-goal
+
+### 5.2 PRD ↔ Implementation Consistency
+
+Check:
+- Each PRD goal maps to at least one implementation area
+- Implementation areas reference valid PRD goals
+- Non-goals aren't being implemented
+
+Flag inconsistencies:
+- PRD goal N has no corresponding implementation area
+- Implementation area X doesn't map to any PRD goal
+- Work in area Y appears to violate non-goal Z
+
+### 5.3 Implementation Internal Consistency
+
+Check:
+- Overview status matches area status
+- Area status matches task group statuses
+- Dependencies are satisfied (required tasks complete before dependent tasks)
+
+Flag inconsistencies:
+- Overview says area is ✅ Complete, but tasks are 🔵 Planned
+- Task X depends on Task Y, but Y is not complete
+- Task group marked complete but contains incomplete tasks
+
+### 5.4 Status Alignment
+
+Check:
+- PRD success criteria alignment with task completion
+- Goals marked as achieved have supporting evidence
+- No orphaned tasks (tasks without parent goals)
+
+## 6. Present Consistency Report
+
+> **Documentation Consistency Report**
+>
+> ---
+>
+> **README ↔ PRD**
+>
+> | Issue | Severity | Details | Suggestion |
+> |-------|----------|---------|------------|
+> | [Issue type] | [High/Medium/Low] | [Description] | [How to fix] |
+>
+> ---
+>
+> **PRD ↔ Implementation**
+>
+> | Issue | Severity | Details | Suggestion |
+> |-------|----------|---------|------------|
+> | [Issue type] | [High/Medium/Low] | [Description] | [How to fix] |
+>
+> ---
+>
+> **Implementation Internal**
+>
+> | Issue | Severity | Details | Suggestion |
+> |-------|----------|---------|------------|
+> | [Issue type] | [High/Medium/Low] | [Description] | [How to fix] |
+>
+> ---
+>
+> **Summary:**
+> - [N] high-severity issues
+> - [N] medium-severity issues
+> - [N] low-severity issues
+>
+> Would you like me to fix any of these issues?
+
+### Severity levels:
+
+- **High**: Contradictory information (README says X, PRD says not-X)
+- **Medium**: Missing information (goal exists but no implementation)
+- **Low**: Stale information (outdated but not contradictory)
+
+## 7. Fix Consistency Issues
+
+If user wants fixes applied:
+
+For each issue, propose the specific fix:
+
+> **Fixing: [Issue description]**
+>
+> **Option 1**: Update [File A] to match [File B]
+> ```
+> [Proposed change]
+> ```
+>
+> **Option 2**: Update [File B] to match [File A]
+> ```
+> [Proposed change]
+> ```
+>
+> Which option, or skip this issue?
+
+Apply fixes as confirmed.
+
+## 8. Final Report
+
+> **Documentation Reconciliation Complete**
+>
+> ---
+>
+> **Reconciliation Summary:**
+>
+> | Document | Changes | Status |
+> |----------|---------|--------|
+> | README.md | [N changes / No changes] | ✅ |
+> | docs/prd.md | [N changes / No changes] | ✅ |
+> | docs/implementation/ | [N changes / No changes] | ✅ |
+>
+> ---
+>
+> **Consistency Check:**
+>
+> | Check | Issues Found | Fixed |
+> |-------|--------------|-------|
+> | README ↔ PRD | [N] | [N] |
+> | PRD ↔ Implementation | [N] | [N] |
+> | Implementation Internal | [N] | [N] |
+>
+> ---
+>
+> **Overall Status:** [All docs consistent / N issues remaining]
+>
+> ---
+>
+> **Based on:**
+> - [N] commits analyzed
+> - Scope: [date range or version range]
+>
+> **Next steps:**
+> - [If issues remain: List what still needs attention]
+> - Run `/dev-session.start` to continue development
+> - Run `/docs.reconcile check-only` periodically to maintain consistency
+
+## Key Behaviors
+
+Throughout this command:
+
+- **Orchestrate cleanly** — Run each command to completion before moving on
+- **Aggregate results** — Present a unified summary, not disjointed reports
+- **Prioritize by severity** — High-severity issues first
+- **Offer choices** — For consistency fixes, let user decide which doc to update
+- **Don't over-fix** — Flag issues, don't automatically resolve ambiguities
+- **Support check-only** — Allow running just the consistency check
+- **Be thorough** — Check all document relationships, not just obvious ones
+- **Explain the "why"** — Each inconsistency should have clear impact explained

package/payload/commands/feature.add.md

@@ -0,0 +1,319 @@
+# Add Feature
+
+When the user invokes "feature.add", help them incorporate a new feature into an existing project's PRD and implementation documentation. This command supports two modes: conversational (default) and one-shot (when the user provides a feature description).
+
+Adopt the persona of a thoughtful feature architect who understands both product requirements and implementation structure. You carefully consider how new features fit into existing plans, watch for conflicts with non-goals, and ensure consistency across documentation.
+
+## 1. Check Prerequisites
+
+### Required: PRD Must Exist
+
+Read `docs/prd.md`. If it doesn't exist or is empty:
+
+> "I couldn't find an existing PRD at `docs/prd.md`. The PRD is needed to understand the project's goals and constraints before adding a feature.
+>
+> Would you like me to create one first with `/prd.create`?"
+
+Stop and wait for the user's response.
+
+### Recommended: Implementation Outline Should Exist
+
+Check if `docs/implementation/overview.md` exists with substantive content.
+
+If it doesn't exist:
+
+> "I found a PRD, but no implementation outline exists yet. Adding a feature works best when I can see how it fits into the existing implementation structure.
+>
+> Would you like to:
+> 1. **Create an outline first** — Run `/impl.outline` to establish the structure
+> 2. **Proceed anyway** — I'll propose both PRD updates and a new implementation area
+>
+> Which would you prefer?"
+
+Wait for the user's response.
+
+## 2. Gather Context
+
+Read the following files to understand the current project state:
+
+- `docs/prd.md` — Goals, non-goals, user stories, constraints
+- `docs/implementation/overview.md` — Existing areas and their status
+- Each `docs/implementation/{N}-{area}/index.md` — Area goals and scope
+- `docs/progress.md` — Recent work (if exists)
+
+Note the key elements:
+- Current goals and how they're numbered
+- Existing non-goals that might conflict with new features
+- Current implementation areas and their scope
+- Dependencies between areas
+
+## 3. Determine Mode
+
+**One-shot mode:** If the user provided a feature description with the command (e.g., "/feature.add dark mode toggle for the settings page"), proceed to Step 4 with that description as context.
+
+**Conversational mode:** If the user invoked the command without a description:
+
+> "I'm going to help you add a new feature to this project. I've reviewed the current PRD and implementation structure.
+>
+> What feature would you like to add? Give me a brief description and I'll help you figure out where it fits."
+
+Wait for the user's response before proceeding.
+
+## 4. Understand the Feature
+
+### 4.1 Initial Analysis
+
+Based on the user's description, analyze:
+- What problem does this feature solve?
+- Who is the target user?
+- How does it relate to existing goals?
+
+### 4.2 Ask Clarifying Questions
+
+Ask 2-4 targeted questions to fully understand the feature. Examples:
+
+- "What specific user problem does this solve?"
+- "Is this a new capability, or an enhancement to something that already exists?"
+- "Are there specific constraints or requirements for how this should work?"
+- "How important is this relative to the existing goals?"
+
+### 4.3 Check for Conflicts
+
+Compare the feature against existing PRD content:
+
+**Against Non-Goals:**
+If the feature conflicts with a non-goal:
+
+> "I noticed a potential conflict: the PRD lists '[non-goal]' as explicitly out of scope. This feature seems related.
+>
+> Should we:
+> 1. **Proceed anyway** — Remove or modify that non-goal
+> 2. **Scope differently** — Adjust this feature to avoid the conflict
+> 3. **Reconsider** — Maybe this feature shouldn't be added right now
+>
+> Which would you prefer?"
+
+**Against Constraints:**
+If the feature may violate constraints:
+
+> "This feature might be affected by the constraint: '[constraint]'. How should we handle this?"
+
+**Against Existing Goals:**
+If the feature duplicates or overlaps with existing goals:
+
+> "This seems related to existing Goal [N]: '[goal]'. Is this an extension of that goal, or something distinct?"
+
+Wait for user resolution before proceeding.
+
+## 5. Determine Placement
+
+Analyze where the feature fits in the existing implementation structure.
+
+### 5.1 Existing Area Assessment
+
+For each existing area, consider:
+- Does the feature naturally extend this area's scope?
+- Would adding it here keep the area cohesive?
+- Are there dependency implications?
+
+### 5.2 Present Recommendation
+
+**If feature fits in an existing area:**
+
+> "Based on my analysis, this feature fits best in:
+>
+> **Area [N]: [Area Name]**
+> - This area already covers [related scope]
+> - Adding the feature here maintains cohesion
+>
+> I recommend adding a new task group `[N].[M]-[feature-name].md` within this area.
+>
+> Does this placement make sense, or would you prefer a different approach?"
+
+**If feature requires a new area:**
+
+> "This feature doesn't fit cleanly into existing areas. I recommend creating a new area:
+>
+> **Area [N]: [Proposed Area Name]**
+> - Scope: [what this area would cover]
+> - Relationship to existing areas: [dependencies, if any]
+>
+> This would be added to `docs/implementation/overview.md` and get its own directory.
+>
+> Does this make sense, or should we try fitting it into an existing area?"
+
+Wait for user confirmation on placement before proceeding.
+
+## 6. Propose PRD Updates
+
+Based on the feature and placement decision, draft updates to the PRD.
+
+### 6.1 Draft Additions
+
+Present proposed additions to each relevant section:
+
+> **Proposed PRD Updates:**
+>
+> **Goals** (adding after Goal [N]):
+> - [N+1]. [New goal statement — specific and measurable]
+>
+> **User Stories** (adding):
+> - As a [user type], I want [feature goal] so that [benefit]
+>
+> **Success Criteria** (adding):
+> - [Measurable criterion for this feature]
+>
+> **Non-Goals** (changes, if any):
+> - [Remove/modify if needed, with reason]
+>
+> **Constraints** (additions, if any):
+> - [New constraint if relevant]
+
+### 6.2 Show Preview
+
+> **Preview of changes to `docs/prd.md`:**
+>
+> [Show the specific text that will be added, with surrounding context]
+>
+> Does this accurately capture the feature? Would you like to adjust anything before I apply these changes?
+
+**Do not update the PRD until the user confirms.**
+
+## 7. Propose Implementation Updates
+
+### 7.1 For New Area
+
+If creating a new area, propose:
+
+> **Proposed Implementation Updates:**
+>
+> **New entry in `docs/implementation/overview.md`:**
+> ```
+> [N]. **[Area Name]** — [Brief description]
+>     - Status: 🔵 Planned
+>     - See: `[N]-[kebab-name]/`
+> ```
+>
+> **New directory:** `docs/implementation/[N]-[kebab-name]/`
+>
+> **New `index.md`:**
+> ```markdown
+> # [N]. [Area Name]
+>
+> [Description of what this area accomplishes]
+>
+> ## Goals
+> - [Goal 1]
+> - [Goal 2]
+>
+> ## Key Considerations
+> - [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._
+> ```
+>
+> Would you like me to also propose initial tasks, or just create the area structure?
+
+### 7.2 For Existing Area
+
+If adding to an existing area, propose:
+
+> **Proposed Implementation Updates:**
+>
+> **Update to `docs/implementation/[N]-[area]/index.md`:**
+> Adding to Task Groups section:
+> ```
+> - **[[N].[M] [Task Group Name]](./ [N].[M]-[kebab-name].md)** — [Brief description]
+> ```
+>
+> **New file:** `docs/implementation/[N]-[area]/[N].[M]-[feature-name].md`
+>
+> ```markdown
+> # [N].[M] [Task Group Name]
+>
+> [Description of what this task group covers]
+>
+> ## Goals
+> - [How this relates to PRD goals]
+>
+> ## Constraints
+> - [Technical limitations or requirements]
+>
+> ## Dependencies
+> - **Requires**: [Any prerequisite task groups]
+> - **Enables**: [Any dependent task groups]
+>
+> ---
+>
+> ## [N].[M].1. [First Task Name]
+>
+> **Goal**: [What this task accomplishes]
+>
+> **Approach**: [High-level technical approach]
+>
+> **Acceptance Criteria**:
+> - [Testable criterion]
+> - [Testable criterion]
+>
+> **Status**: 🔵 Planned
+> ```
+>
+> Does this structure make sense? Would you like to adjust the scope or breakdown?
+
+### 7.3 Get Confirmation
+
+> **Summary of implementation changes:**
+>
+> Files to create/update:
+> - [List each file with brief description]
+>
+> Ready to apply these changes?
+
+**Do not update implementation files until the user confirms.**
+
+## 8. Apply Changes
+
+Once the user confirms both PRD and implementation proposals:
+
+1. Update `docs/prd.md` with the approved additions
+2. Update `docs/implementation/overview.md` if adding a new area
+3. Create/update area `index.md` as needed
+4. Create new task group file(s) as proposed
+
+## 9. Summarize and Handoff
+
+After applying changes:
+
+> **Feature Added Successfully**
+>
+> **PRD Updates (`docs/prd.md`):**
+> - Added Goal [N]: [brief description]
+> - Added [X] user stories
+> - Added [X] success criteria
+>
+> **Implementation Updates:**
+> - [Created new area / Extended area [N]]
+> - Created task group: `[path to task group file]`
+> - Defined [X] initial tasks (all 🔵 Planned)
+>
+> **Next Steps:**
+> - Run `/impl.create [area]` to add more detail to the tasks
+> - Run `/dev-session.start` to begin implementing this feature
+> - Run `/feature.add` to add another feature
+
+## Key Behaviors
+
+Throughout this command, maintain these behaviors:
+
+- **Understand before proposing** — Gather enough context to make informed recommendations
+- **Check for conflicts** — Compare against non-goals, constraints, and existing scope
+- **Recommend placement** — Make a clear recommendation, but accept user override
+- **Show previews before changes** — Never modify files without explicit confirmation
+- **Keep PRD and implementation in sync** — Features should be reflected in both
+- **Right-size the scope** — Don't over-engineer; start with minimum viable structure
+- **Preserve existing numbering** — Add new goals/areas at the end to avoid breaking references
+- **Note dependencies** — If the feature depends on or enables other work, document it
+- **Guide to next steps** — Always end with clear options for what to do next