flight-rules 0.13.9 → 0.15.0

package/dist/index.js

@@ -6,6 +6,7 @@ import { upgrade } from './commands/upgrade.js';
 import { adapter } from './commands/adapter.js';
 import { update } from './commands/update.js';
 import { ralph } from './commands/ralph.js';
+import { parallel } from './commands/parallel.js';
 import { getCliVersion } from './utils/files.js';
 import { checkForUpdate, shouldSkipUpdateCheck } from './utils/version-check.js';
 import { isInteractive } from './utils/interactive.js';
@@ -121,6 +122,15 @@ async function main() {
                 branch: parseBranchArg(args),
             });
             break;
+        case 'parallel': {
+            const subcommand = args[0] || '';
+            const subArgs = args.slice(1).filter(a => !a.startsWith('--'));
+            const parallelOptions = {
+                force: args.includes('--force'),
+            };
+            await parallel(subcommand, subArgs, parallelOptions);
+            break;
+        }
         case undefined:
         case '--help':
         case '-h':
@@ -144,6 +154,7 @@ ${pc.bold('Commands:')}
   adapter     Generate agent-specific adapter files
   update      Update the Flight Rules CLI itself
   ralph       Run autonomous agent loop through task groups
+  parallel    Manage parallel dev sessions with git worktrees
 
 ${pc.bold('Upgrade Options:')}
   --version <version>   Upgrade to a specific version (e.g., 0.1.4)
@@ -165,6 +176,15 @@ ${pc.bold('Ralph Options:')}
   --dry-run                 Show what would be executed without running
   --verbose                 Show full Claude output during execution
 
+${pc.bold('Parallel Subcommands:')}
+  parallel create <name>    Create a new parallel session in an isolated worktree
+  parallel status           Show all active parallel sessions
+  parallel cleanup          Detect and clean up orphaned sessions
+  parallel remove <name>    Remove a session (with merge workflow)
+
+${pc.bold('Parallel Options:')}
+  --force                   Skip confirmations (cleanup, remove)
+
 ${pc.bold('Examples:')}
   flight-rules init
   flight-rules upgrade
@@ -177,6 +197,10 @@ ${pc.bold('Examples:')}
   flight-rules ralph --area 2 --branch
   flight-rules ralph --area 2-cli-core --branch feature/cli-work
   flight-rules ralph --dry-run
+  flight-rules parallel create auth-refactor
+  flight-rules parallel status
+  flight-rules parallel cleanup
+  flight-rules parallel remove auth-refactor
 `);
 }
 /**

package/package.json

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

package/payload/commands/backlog.add.md

@@ -0,0 +1,77 @@
+# Add to Backlog
+
+When the user invokes "backlog.add", capture an idea with minimum friction. This command prioritizes speed — the user should go from thought to captured file in seconds.
+
+## 1. Determine Mode
+
+**One-shot mode (primary):** If the user provided a description with the command (e.g., "/backlog.add dark mode for settings page"), proceed directly to Step 3 using that text as the idea description.
+
+**Conversational mode:** If the user invoked the command without a description:
+
+> "What idea would you like to capture? Just describe it in a sentence or two — we can flesh it out later with `/backlog.clarify`."
+
+Wait for the user's response.
+
+## 2. Gather Title
+
+If the user provided a one-shot description, derive a concise title from it (5-8 words max).
+
+If in conversational mode and the description is long or complex, ask:
+
+> "Got it. What would you call this in a few words? (This becomes the filename.)"
+
+If the description is short enough to serve as the title, use it directly — don't ask.
+
+## 3. Check for Duplicates
+
+Convert the title to kebab-case for the filename (e.g., "Dark Mode for Settings" → `dark-mode-for-settings.md`).
+
+Check if `docs/backlog/` contains a file with the same or very similar name.
+
+If a duplicate exists:
+
+> "There's already a backlog item with a similar name: `docs/backlog/[existing-file]`. Would you like to:
+> 1. **Add anyway** — Create a new file with a slightly different name
+> 2. **View existing** — Open the existing item instead
+> 3. **Cancel** — Skip this capture"
+
+Wait for the user's response.
+
+## 4. Create the Backlog File
+
+Ensure `docs/backlog/` exists (create it if needed).
+
+Create the file at `docs/backlog/[kebab-case-title].md` with this template:
+
+```markdown
+# [Title]
+
+**Captured**: [YYYY-MM-DD]
+**Status**: Raw
+**Tags**:
+**Priority**:
+
+## Idea
+
+[User's description]
+```
+
+- Use today's date for the Captured field
+- Tags and Priority are left blank intentionally — they're optional
+- The Idea section contains the user's description as-is, without editing or expanding it
+
+## 5. Confirm
+
+> "Captured: `docs/backlog/[filename].md`
+>
+> **Next steps when you're ready:**
+> - `/backlog.clarify [filename]` — Flesh out this idea with more detail
+> - `/backlog.list` — See all your backlog items
+> - `/backlog.add` — Capture another idea"
+
+## Key Behaviors
+
+- **Speed over completeness** — Don't ask unnecessary questions. Title + description is enough.
+- **No required fields beyond description** — Tags and priority are always optional and left blank at capture time.
+- **Don't embellish** — Write the user's idea as they described it. Don't add your own analysis or suggestions.
+- **Create the directory if needed** — `docs/backlog/` may not exist yet.

package/payload/commands/backlog.clarify.md

@@ -0,0 +1,138 @@
+# Clarify Backlog Item
+
+When the user invokes "backlog.clarify", help them flesh out a raw idea through interactive conversation. The goal is to add enough structure that the idea becomes actionable — without over-formalizing it.
+
+## 1. Find the Backlog Item
+
+If the user provided an identifier with the command (e.g., "/backlog.clarify dark-mode"), search `docs/backlog/` for a matching file:
+
+- Try exact filename match first: `docs/backlog/[identifier].md`
+- Then try with `.md` appended: `docs/backlog/[identifier].md`
+- Then try partial match against filenames in `docs/backlog/`
+
+If no identifier was provided, list the files in `docs/backlog/` (excluding `archive/`) and ask:
+
+> "Which backlog item would you like to clarify?"
+>
+> [numbered list of items with their Status]
+
+Wait for the user to select one.
+
+**If no match found:**
+
+> "I couldn't find a backlog item matching '[identifier]'. Run `/backlog.list` to see all items, or `/backlog.add` to create a new one."
+
+Stop.
+
+**If multiple matches found:**
+
+> "I found multiple items matching '[identifier]':
+>
+> [numbered list of matching items]
+>
+> Which one did you mean?"
+
+Wait for the user to select one.
+
+## 2. Read the Current Item
+
+Read the matched file. Note the current status and content.
+
+Present a summary:
+
+> **Current item: [Title]**
+> - **Status**: [Raw/Clarified]
+> - **Idea**: [quote the Idea section]
+
+If the item is already Clarified:
+
+> "This item has already been clarified. Would you like to refine it further, or is it ready to promote with `/backlog.promote`?"
+
+If the user wants to refine further, continue. Otherwise, stop.
+
+## 3. Ask Clarifying Questions
+
+Ask 3-5 targeted questions to draw out more detail. Choose from these categories based on what's missing:
+
+**Problem understanding:**
+- "What problem does this solve? Who experiences this problem?"
+- "How are you (or users) working around this today?"
+- "What happens if we never build this?"
+
+**Scope and approach:**
+- "What's the simplest version of this that would be useful?"
+- "Are there parts of this that could be separate ideas?"
+- "Do you have a rough sense of how this would work technically?"
+
+**Constraints and dependencies:**
+- "Does this depend on anything else being built first?"
+- "Are there constraints (time, tech, compatibility) to keep in mind?"
+- "Does this conflict with or overlap with any existing features?"
+
+**Priority signals:**
+- "How important is this relative to what you're working on now?"
+- "Is this a 'nice to have' or a 'need to have'?"
+
+Ask questions conversationally — 1-2 at a time, not all at once. Adapt follow-ups based on the user's answers.
+
+## 4. Update the File
+
+After the conversation, update the backlog file with the new detail. Preserve the original Idea section and add new sections below it:
+
+```markdown
+# [Title]
+
+**Captured**: [original date]
+**Status**: Clarified
+**Tags**: [add if the conversation revealed natural tags]
+**Priority**: [add if the user indicated priority]
+
+## Idea
+
+[Original idea text — preserved as-is]
+
+## Problem
+
+[What problem this solves and who it affects]
+
+## Possible Approach
+
+[How this might be implemented, at a high level]
+
+## Open Questions
+
+- [Unresolved questions from the conversation]
+
+## Notes
+
+[Any other relevant context from the conversation]
+```
+
+**Rules for updating:**
+- Change Status from Raw → Clarified
+- Preserve the original Idea text exactly
+- Only add Tags/Priority if the conversation naturally surfaced them — don't ask just to fill fields
+- Omit sections that have no content (e.g., skip Open Questions if there are none)
+
+Show the user a preview of the updated content before writing:
+
+> "Here's the clarified version. Does this capture everything, or would you like to adjust anything?"
+
+Wait for confirmation before writing.
+
+## 5. Confirm
+
+> "Updated: `docs/backlog/[filename].md`
+>
+> **Next steps:**
+> - `/backlog.promote [filename]` — Move this into the PRD and implementation workflow
+> - `/backlog.clarify [another-item]` — Clarify another idea
+> - `/backlog.list` — See all backlog items"
+
+## Key Behaviors
+
+- **Preserve the original idea** — Never modify the Idea section. Add new sections below it.
+- **Conversational, not interrogative** — Ask 1-2 questions at a time, not a checklist.
+- **Don't over-formalize** — This is a backlog item, not a spec. Keep it concise.
+- **Surface priority naturally** — If the user's answers suggest priority, note it. Don't force a ranking exercise.
+- **Preview before writing** — Always show the updated content and wait for confirmation.

package/payload/commands/backlog.list.md

@@ -0,0 +1,65 @@
+# List Backlog
+
+When the user invokes "backlog.list", show a summary of all backlog items.
+
+## 1. Read Backlog Items
+
+Read all Markdown files in `docs/backlog/` (excluding the `archive/` subdirectory).
+
+If `docs/backlog/` doesn't exist or contains no files:
+
+> "No backlog items found. Run `/backlog.add` to capture your first idea."
+
+Stop.
+
+## 2. Parse Each Item
+
+For each file, extract the frontmatter fields:
+- **Title** — from the `# Title` heading
+- **Status** — Raw, Clarified, or Promoted
+- **Tags** — if present
+- **Priority** — if present
+- **Captured** — the date
+
+## 3. Apply Filters (Optional)
+
+If the user provided filters with the command (e.g., "/backlog.list clarified" or "/backlog.list tag:api"), apply them:
+
+- **By status**: Show only items matching the given status (Raw, Clarified)
+- **By tag**: Show only items with the given tag
+- **By priority**: Show only items with the given priority
+
+If no filters, show all items.
+
+## 4. Present the List
+
+Display items sorted by capture date (newest first):
+
+> **Backlog** — [N] items: [X] Raw, [Y] Clarified
+>
+> | # | Title | Status | Tags | Priority | Captured |
+> |---|-------|--------|------|----------|----------|
+> | 1 | [Title] | Raw | | | 2026-02-11 |
+> | 2 | [Title] | Clarified | api, auth | High | 2026-02-10 |
+> | ... | | | | | |
+
+- Leave Tags and Priority blank in the table when not set (don't show "none" or "—")
+- If there are archived items, mention the count at the bottom
+
+If there are archived items in `docs/backlog/archive/`:
+
+> _[N] promoted items in archive/_
+
+## 5. Suggest Next Actions
+
+> **Actions:**
+> - `/backlog.add` — Capture a new idea
+> - `/backlog.clarify [title]` — Flesh out a Raw item
+> - `/backlog.promote [title]` — Move a Clarified item into the PRD workflow
+
+## Key Behaviors
+
+- **Quick scan, not deep read** — Extract only the header fields, don't analyze the full content.
+- **Graceful with missing fields** — Tags and Priority will often be blank. Don't treat that as an error.
+- **Newest first** — Most recent ideas are most relevant.
+- **Exclude archive** — Promoted items live in `docs/backlog/archive/` and shouldn't clutter the active list.

package/payload/commands/backlog.promote.md

@@ -0,0 +1,98 @@
+# Promote Backlog Item
+
+When the user invokes "backlog.promote", graduate a backlog idea into the formal PRD and implementation workflow by feeding it into `/feature.add`.
+
+## 1. Find the Backlog Item
+
+If the user provided an identifier with the command (e.g., "/backlog.promote dark-mode"), search `docs/backlog/` for a matching file:
+
+- Try exact filename match first: `docs/backlog/[identifier].md`
+- Then try with `.md` appended: `docs/backlog/[identifier].md`
+- Then try partial match against filenames in `docs/backlog/`
+
+If no identifier was provided, list the files in `docs/backlog/` (excluding `archive/`) and ask:
+
+> "Which backlog item would you like to promote to a full feature?"
+>
+> [numbered list of items with their Status]
+
+Wait for the user to select one.
+
+**If no match found:**
+
+> "I couldn't find a backlog item matching '[identifier]'. Run `/backlog.list` to see all items."
+
+Stop.
+
+## 2. Read and Present the Item
+
+Read the matched file. Present the content:
+
+> **Promoting: [Title]**
+> - **Status**: [Raw/Clarified]
+> - **Idea**: [quote the Idea section]
+> - **Problem**: [quote if present]
+> - **Possible Approach**: [quote if present]
+
+If the item is Raw (not yet Clarified):
+
+> "This idea hasn't been clarified yet. Promoting a Raw item is fine, but you'll get better results if you clarify it first.
+>
+> Would you like to:
+> 1. **Clarify first** — Run `/backlog.clarify` to flesh it out
+> 2. **Promote as-is** — Proceed with the raw idea"
+
+Wait for the user's response. If they choose to clarify first, stop and let them run `/backlog.clarify`.
+
+## 3. Launch Feature Add Workflow
+
+Feed the backlog item's content into the `/feature.add` workflow as context. Present it as:
+
+> "I'll now run the feature addition workflow using this backlog item as the starting point."
+
+Proceed to follow the full `/feature.add` process (from `feature.add.md`), using the backlog item's description, problem statement, and approach as the feature description input. This means:
+
+1. Check prerequisites (PRD exists, implementation outline exists)
+2. Gather context from existing docs
+3. Skip the "what feature?" question — use the backlog item as the answer
+4. Continue with understanding, placement, PRD updates, implementation updates, etc.
+
+The agent should follow the full `feature.add.md` workflow from Step 4 onward, treating the backlog item content as the user's feature description.
+
+## 4. Archive the Backlog Item
+
+After the `/feature.add` workflow completes successfully (PRD and implementation updates applied):
+
+Ensure `docs/backlog/archive/` exists (create if needed).
+
+Update the backlog file:
+- Change Status to **Promoted**
+- Add a **Promoted To** field with references to where the idea landed
+
+```markdown
+**Status**: Promoted
+**Promoted To**: PRD Goal [N], Implementation [area/spec reference]
+```
+
+Move the file from `docs/backlog/` to `docs/backlog/archive/`.
+
+## 5. Confirm
+
+> "Promoted and archived: `docs/backlog/archive/[filename].md`
+>
+> **What was created:**
+> - PRD Goal [N]: [brief description]
+> - Implementation spec: `[path to spec file]`
+>
+> **Next steps:**
+> - `/impl.create` or `/impl.clarify` to add detail to the new spec
+> - `/dev-session.start` to begin implementing
+> - `/backlog.list` to see remaining backlog items"
+
+## Key Behaviors
+
+- **Recommend clarifying first** — Raw items work, but Clarified items produce better features.
+- **Reuse `/feature.add` fully** — Don't reinvent the feature addition workflow. Follow `feature.add.md` for the actual PRD/implementation work.
+- **Archive, don't delete** — Promoted items move to `docs/backlog/archive/` so there's a record.
+- **Cross-reference** — The archived file should say where the idea ended up (PRD goal number, implementation area).
+- **Don't modify the original idea** — The Idea section stays as-is, even in the archived version.

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

@@ -76,4 +76,19 @@ If yes, help prepare a commit message that:
 - References the session log file
 - Is concise but meaningful
 
+## 8. Handle Parallel Session (If Applicable)
+
+If this session is running in a parallel worktree (check if the current directory is inside a `*-sessions/` worktree path, or check `git rev-parse --git-dir` for linked worktrees):
+
+1. **Ensure all changes are committed** — parallel sessions require committed changes before cleanup
+2. **Offer merge strategy:**
+   > "This is a parallel session. How would you like to integrate these changes?"
+   > - **Create a PR** (recommended for review)
+   > - **Merge directly to main** (for small/safe changes)
+   > - **Keep branch for later** (don't merge yet, but clean up worktree)
+   > - **Abandon** (discard all changes)
+
+3. Run `flight-rules parallel remove <session-name>` which will execute the chosen strategy and clean up the worktree
+4. If choosing to create a PR, include the session summary in the PR description
+
 

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

@@ -43,7 +43,25 @@ Include:
 - Technical approach
 - Task breakdown
 
-## 5. Confirm Before Coding
+## 5. Offer Parallel Session (Optional)
+
+After establishing goals, check if the user wants to run this session in parallel:
+
+> "Would you like to run this session in an isolated worktree? This allows other agents to work on the project simultaneously."
+>
+> - **Standard session** (work in main directory)
+> - **Parallel session** (create isolated worktree)
+
+If parallel is chosen:
+
+1. Run `flight-rules parallel create <session-name>` (derive a short kebab-case name from the goals)
+2. Note the worktree path in the session log header: `**Worktree:** <path>`
+3. Instruct the user to open a new terminal in the worktree directory and run `claude`
+4. The rest of the session workflow proceeds normally within the worktree
+
+**Detecting existing parallel context:** If you notice the current directory is inside a `*-sessions/` worktree (check with `git rev-parse --git-dir` — linked worktrees show `.git/worktrees/<name>`), note this in the session log and skip offering the parallel option.
+
+## 6. Confirm Before Coding
 
 Present the plan to the user and ask:
 

package/payload/commands/parallel.cleanup.md

@@ -0,0 +1,18 @@
+# Parallel Session Cleanup
+
+When the user invokes "parallel cleanup", detect and clean up orphaned parallel sessions.
+
+## Process
+
+1. Run `flight-rules parallel cleanup` to scan for orphaned sessions
+2. An orphaned session is one where the manifest entry exists but the worktree directory is missing (e.g., the user closed their terminal without running `/dev-session.end`)
+3. For each orphan, the CLI will:
+   - Remove the entry from the manifest
+   - Delete the associated git branch
+4. If no orphans are found, report that everything is clean
+
+## When to Use
+
+- After a crash or unexpected terminal closure during a parallel session
+- If `flight-rules parallel status` shows sessions marked as orphaned
+- As periodic maintenance when using parallel sessions frequently

package/payload/commands/parallel.status.md

@@ -0,0 +1,25 @@
+# Parallel Session Status
+
+When the user invokes "parallel status", show the state of all active parallel sessions.
+
+## Process
+
+1. Run `flight-rules parallel status` to get the current state
+2. If there are active sessions, display them clearly with navigation instructions
+3. If there are orphaned sessions, suggest running `flight-rules parallel cleanup`
+4. Show the main directory status (clean/dirty, current branch)
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `flight-rules parallel create <name>` | Start a new parallel session |
+| `flight-rules parallel status` | Show this status view |
+| `flight-rules parallel cleanup` | Clean up orphaned sessions |
+| `flight-rules parallel remove <name>` | End a session with merge workflow |
+
+To switch to a session, open a new terminal:
+```
+cd <worktree-path>
+claude
+```