flight-rules 0.14.0 → 0.15.0

package/dist/commands/init.js

@@ -15,6 +15,7 @@ async function copyDocsFromTemplates(templatesDir, docsDir, skipExisting) {
     ensureDir(docsDir);
     ensureDir(join(docsDir, 'implementation'));
     ensureDir(join(docsDir, 'session_logs'));
+    ensureDir(join(docsDir, 'backlog'));
     for (const file of DOC_FILES) {
         const srcPath = join(templatesDir, file.src);
         const destPath = join(docsDir, file.dest);

package/dist/commands/upgrade.js

@@ -20,6 +20,7 @@ function copyNewDocsFromTemplates(templatesDir, docsDir) {
     ensureDir(docsDir);
     ensureDir(join(docsDir, 'implementation'));
     ensureDir(join(docsDir, 'session_logs'));
+    ensureDir(join(docsDir, 'backlog'));
     const copied = [];
     for (const file of DOC_FILES) {
         const srcPath = join(templatesDir, file.src);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flight-rules",
-  "version": "0.14.0",
+  "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.14.0
+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.