flight-rules 0.10.2 → 0.12.0

package/package.json

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

package/payload/commands/feature.add.md

@@ -300,7 +300,8 @@ After applying changes:
 > - Defined [X] initial tasks (all 🔵 Planned)
 >
 > **Next Steps:**
-> - Run `/impl.create [area]` to add more detail to the tasks
+> - Run `/impl.create [area]` to add new task groups or tasks
+> - Run `/impl.clarify [area]` to refine existing task definitions
 > - Run `/dev-session.start` to begin implementing this feature
 > - Run `/feature.add` to add another feature
 

package/payload/commands/impl.clarify.md

@@ -0,0 +1,183 @@
+# Clarify Implementation
+
+When the user invokes this command, help them refine and clarify existing implementation specs through targeted questions.
+
+## 1. Read Existing Implementation
+
+Read `docs/implementation/overview.md`. If it doesn't exist or is empty:
+
+> "I couldn't find existing implementation specs at `docs/implementation/overview.md`. Would you like me to create an outline first with `/impl.outline`?"
+
+Stop and wait for the user's response.
+
+Also read `docs/prd.md` for context on goals and constraints.
+
+## 2. Determine Scope
+
+Check if the user specified a scope with the command:
+- `/impl.clarify` → Ask what scope they want
+- `/impl.clarify 1-authentication` → Clarify that area
+- `/impl.clarify 1.2` → Clarify that task group
+- `/impl.clarify 1.2.3` → Clarify that specific task
+
+If no argument provided, first analyze the existing specs to identify areas that could benefit from clarification, then ask:
+
+> **Current Implementation Structure:**
+>
+> [List areas with brief assessment of clarity]
+>
+> **Areas that may need clarification:**
+> - [Area/task group with vague goals or missing acceptance criteria]
+> - [Area/task group with unclear dependencies]
+>
+> Which would you like to clarify? You can specify:
+> - An area (e.g., `1-authentication`)
+> - A task group (e.g., `1.2`)
+> - A specific task (e.g., `1.2.3`)
+
+Wait for the user to specify what to clarify.
+
+## 3. Analyze Current Content
+
+Once a scope is identified, read the relevant files and analyze for clarity issues:
+
+### For Area Scope
+
+Read `docs/implementation/{N}-{area}/index.md` and all task group files within.
+
+Look for:
+- Vague or missing area goals
+- Task groups without clear scope boundaries
+- Missing or incomplete key considerations
+- Unclear relationships between task groups
+
+### For Task Group Scope
+
+Read `docs/implementation/{N}-{area}/{N}.{M}-topic.md`.
+
+Look for:
+- Vague task group goals
+- Tasks without clear acceptance criteria
+- Missing or unclear approach descriptions
+- Undocumented dependencies
+- Tasks that seem too large or too small
+
+### For Task Scope
+
+Read the specific task within its task group file.
+
+Look for:
+- Goal that doesn't clearly state what "done" means
+- Missing or vague acceptance criteria
+- Approach that lacks technical specificity
+- Missing dependencies on other tasks
+
+## 4. Present Findings
+
+Summarize the current content and what needs clarification:
+
+> **Current [Area/Task Group/Task]:**
+>
+> [Quote or summarize the current content]
+>
+> **Areas needing clarification:**
+> - [Specific issue 1]
+> - [Specific issue 2]
+
+## 5. Ask Targeted Questions
+
+Ask 1-3 specific questions to draw out more detail. Tailor questions to what's unclear:
+
+**Goals:**
+- "What specific outcome does this [area/task group/task] produce?"
+- "How does this map to the PRD goals?"
+- "What would be different in the codebase when this is complete?"
+
+**Acceptance Criteria:**
+- "How would you verify this task is complete?"
+- "What specific behavior should be testable?"
+- "Are there edge cases that need to be handled?"
+
+**Approach:**
+- "What's the high-level technical strategy here?"
+- "Are there specific patterns or libraries you want to use?"
+- "What files or modules will this touch?"
+
+**Dependencies:**
+- "Does this require any other tasks to be completed first?"
+- "What other tasks depend on this being done?"
+- "Are there external dependencies (APIs, services) to consider?"
+
+**Scope:**
+- "This task seems broad — should it be broken into smaller tasks?"
+- "This seems very specific — is it part of a larger task group?"
+
+## 6. Push Back on Vagueness
+
+If the user's answers are vague or unmeasurable, push back:
+
+- ❌ "Implement authentication" → ✅ "Create login endpoint that validates credentials against user table and returns JWT token"
+- ❌ "Make it work" → ✅ "Function returns correct result for inputs X, Y, Z as verified by unit tests"
+- ❌ "Handle errors" → ✅ "Invalid input returns 400 with error message; server errors return 500 and log to error tracking"
+
+> "That's a good direction, but it's hard to verify completion. What specific behavior or output would you check to confirm this is done?"
+
+## 7. Check for Conflicts
+
+As you clarify, watch for conflicts:
+
+- Dependencies that create circular references
+- Acceptance criteria that contradict other tasks
+- Scope that overlaps with other task groups
+- Approaches that conflict with stated constraints in the PRD
+
+If you spot a conflict:
+
+> "I noticed a potential conflict: [describe conflict]. Should we adjust one of these?"
+
+## 8. Propose Updated Content
+
+After gathering more detail, propose the updated spec:
+
+> **Proposed [Area/Task Group/Task]:**
+>
+> [Show the proposed updated content in full]
+>
+> Does this capture what we discussed, or would you like to adjust it?
+
+Wait for user approval before proceeding.
+
+## 9. Update the Specs
+
+After the user approves the clarified content:
+
+1. Update the relevant file(s) with the new content
+2. Preserve sections that weren't modified
+3. Update any related files if dependencies changed
+
+## 10. Report Changes
+
+Summarize what was changed:
+
+> **Implementation Specs Updated:**
+>
+> **Files modified:**
+> - [File 1]: [brief description of changes]
+>
+> **Sections clarified:**
+> - [Section 1]: [what was improved]
+> - [Section 2]: [what was improved]
+>
+> Would you like to clarify anything else?
+
+## Key Behaviors
+
+Throughout this command, maintain these behaviors:
+
+- **Analyze before asking** — Review existing specs to identify what's actually unclear
+- **Be specific in questions** — Ask about concrete details, not abstract concepts
+- **Push back on vagueness** — Testable > aspirational
+- **Watch for conflicts** — Dependencies and acceptance criteria should be consistent
+- **Propose, don't impose** — Show proposed changes and wait for approval
+- **One scope at a time** — Don't overwhelm with too many changes at once
+- **Map to PRD** — Ensure implementation details align with stated goals and constraints

package/payload/commands/version.bump.md

@@ -0,0 +1,229 @@
+# Bump Version
+
+When the user invokes "version.bump", help them update the project version following semantic versioning conventions. This command supports two modes: one-shot (when the user specifies major/minor/patch) and conversational (analyze commits and recommend).
+
+## 1. Check Prerequisites
+
+### Working Directory Must Be Clean
+
+Run `git status --porcelain` to check for uncommitted changes.
+
+If there are uncommitted changes:
+
+> "There are uncommitted changes in the working directory. Version bumping typically requires a clean working tree.
+>
+> Would you like me to:
+> 1. **Show the changes** — See what's uncommitted
+> 2. **Proceed anyway** — Some version tools allow this
+> 3. **Stop** — Commit or stash changes first
+>
+> Which would you prefer?"
+
+Wait for the user's response.
+
+### Project Type Detection
+
+Detect the project type by checking for these files (in order):
+
+1. `package.json` → npm project
+2. `pyproject.toml` → Python project (Poetry/modern)
+3. `setup.py` → Python project (legacy)
+4. `Cargo.toml` → Rust project
+5. `go.mod` → Go project
+
+If no recognized project file is found:
+
+> "I couldn't detect the project type. What kind of project is this, and where is the version defined?"
+
+Wait for the user's response.
+
+## 2. Determine Mode
+
+**One-shot mode:** If the user provided a bump level with the command (e.g., "version.bump patch", "version.bump minor", "version.bump major"), proceed to Step 5.
+
+**Conversational mode:** If the user invoked the command without specifying a level, proceed to Step 3.
+
+## 3. Find Latest Version Tag
+
+Run one of these commands to find the most recent version tag:
+
+```bash
+git describe --tags --abbrev=0 2>/dev/null
+```
+
+Or if that fails (no tags yet):
+
+```bash
+git tag --sort=-v:refname | head -1
+```
+
+### Handle Tag Formats
+
+Version tags may use different formats:
+- `v1.2.3` (with v prefix)
+- `1.2.3` (without prefix)
+
+Extract the version number regardless of format.
+
+### No Tags Found
+
+If no version tags exist:
+
+> "I couldn't find any version tags in this repository. This appears to be the first release.
+>
+> Current version in package.json: [version]
+>
+> Would you like to:
+> 1. **Tag the current version** — Create a tag for the existing version, then bump
+> 2. **Bump from current** — Just bump the version in package.json without analyzing history
+>
+> Which would you prefer?"
+
+Wait for the user's response.
+
+## 4. Analyze Changes Since Last Tag
+
+### Get Commit History
+
+Run:
+
+```bash
+git log {tag}..HEAD --oneline
+```
+
+Where `{tag}` is the version tag found in Step 3.
+
+### Categorize Changes
+
+Review each commit message and categorize:
+
+**Breaking Changes (→ major bump):**
+- Contains "BREAKING CHANGE" or "BREAKING:"
+- Commit type with exclamation suffix (e.g., "feat!:", "fix!:")
+- Messages indicating removed features, changed APIs, or incompatible changes
+- Words like "remove", "delete", "rename" for public APIs
+
+**New Features (→ minor bump):**
+- Commit type "feat:" or "feature:"
+- Messages containing "add", "new", "implement", "introduce"
+- New capabilities that don't break existing functionality
+
+**Fixes and Maintenance (→ patch bump):**
+- Commit type "fix:", "bugfix:"
+- Commit type "docs:", "style:", "refactor:", "perf:", "test:", "chore:"
+- Messages containing "fix", "correct", "patch", "update", "improve"
+
+### Present Analysis
+
+Present the findings:
+
+> **Changes since {tag}:**
+>
+> **Breaking Changes:** [count]
+> - [list each with commit hash prefix]
+>
+> **New Features:** [count]
+> - [list each with commit hash prefix]
+>
+> **Fixes & Maintenance:** [count]
+> - [list each with commit hash prefix]
+>
+> **Recommendation: {MAJOR|MINOR|PATCH}**
+>
+> [Explain the reasoning, e.g., "There are breaking changes that require a major version bump" or "New features were added without breaking changes, suggesting a minor bump"]
+>
+> Current version: {current}
+> Recommended version: {recommended}
+>
+> Would you like to proceed with this recommendation, or specify a different bump level?
+
+Wait for user confirmation or override.
+
+## 5. Apply Version Bump
+
+Based on the confirmed bump level, apply the change using project-appropriate tooling.
+
+### npm Projects
+
+For projects with `package.json`, use npm's version command:
+
+```bash
+npm version {patch|minor|major}
+```
+
+**Important:** This command:
+- Updates the `version` field in `package.json`
+- Runs the `version` lifecycle script if defined (e.g., for syncing version to other files)
+- Creates a git commit with the version as the message
+- Creates a git tag (e.g., `v1.2.4`)
+
+Do NOT manually create a commit or tag — `npm version` handles this.
+
+### Python Projects (pyproject.toml)
+
+For Poetry projects:
+
+```bash
+poetry version {patch|minor|major}
+```
+
+Then commit and tag manually:
+
+```bash
+git add pyproject.toml
+git commit -m "{new_version}"
+git tag v{new_version}
+```
+
+### Python Projects (setup.py)
+
+Update the `version` parameter in `setup.py`, then commit and tag:
+
+```bash
+git add setup.py
+git commit -m "{new_version}"
+git tag v{new_version}
+```
+
+### Rust Projects
+
+Update the `version` field in `Cargo.toml`, then commit and tag:
+
+```bash
+git add Cargo.toml
+git commit -m "{new_version}"
+git tag v{new_version}
+```
+
+### Other Projects
+
+For unrecognized project types, ask the user which file contains the version and update it manually, then commit and tag.
+
+## 6. Report Result
+
+After applying the version bump:
+
+> **Version bumped successfully**
+>
+> - Previous version: {old_version}
+> - New version: {new_version}
+> - Bump type: {patch|minor|major}
+>
+> **What happened:**
+> - Updated version in {file}
+> - Created commit: {commit_hash}
+> - Created tag: {tag}
+>
+> **Next steps:**
+> - Run `git push && git push --tags` to push the release
+> - Run `/project.release` to execute your full release workflow (if configured)
+
+## Key Behaviors
+
+Throughout this command, maintain these behaviors:
+
+- **Default to patch when uncertain** — If commit analysis is ambiguous, recommend patch (safest)
+- **Respect existing conventions** — Use the same tag format the project already uses (v-prefix or not)
+- **Don't duplicate work** — Let `npm version` or `poetry version` handle what they handle
+- **Explain reasoning** — Always explain why you're recommending a particular bump level
+- **Allow overrides** — User can always specify a different bump level than recommended