planflow-ai 1.0.5 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/.claude/rules/core/autopilot-mode.md +1 -1
  2. package/package.json +1 -1
  3. package/rules/core/autopilot-mode.mdc +114 -91
package/.claude/rules/core/autopilot-mode.md CHANGED
@@ -68,7 +68,7 @@ Check `flow/contracts/` for any relevant integration contracts. If found, note t
68
68
 
69
69
  1. **Read** the file `.claude/commands/discovery-plan.md` to load discovery context
70
70
  2. Execute the discovery skill following that command's instructions
71
- 3. **PAUSE**: Ask user discovery questions as needed (mandatory checkpoint)
71
+ 3. **PAUSE**: Use the `AskUserQuestion` tool to ask clarifying questions about requirements (mandatory checkpoint). Present structured multiple-choice options — do NOT ask as plain text when the tool is available.
72
72
  4. Produce the discovery document in `flow/discovery/`
73
73
  5. Write transition summary (see format below)
74
74
  6. **Auto-proceed** to Step 3 (override the "ask before proceeding" rule)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "planflow-ai",
3
- "version": "1.0.5",
3
+ "version": "1.0.7",
4
4
  "description": "Structured AI-assisted development workflows for discovery, planning, execution, code reviews, and testing",
5
5
  "type": "module",
6
6
  "main": "dist/cli/index.js",
package/rules/core/autopilot-mode.mdc CHANGED
@@ -7,7 +7,7 @@ alwaysApply: true
7
7
 
8
8
  ## Purpose
9
9
 
10
- When `flow/.autopilot` exists, this rule is active. It automatically orchestrates the full plan-flow workflow for feature requests, loading only the relevant command context at each step.
10
+ When `flow/.autopilot` exists, this rule is active. It automatically orchestrates the full plan-flow workflow for feature requests. **You MUST follow every step below in order. Do NOT skip steps. Do NOT jump to implementation without discovery and planning first.**
11
11
 
12
12
  ---
13
13
 
@@ -23,137 +23,162 @@ When `flow/.autopilot` exists, this rule is active. It automatically orchestrate
23
23
 
24
24
  When autopilot is ON, classify every new user input before acting:
25
25
 
26
- ### Category 1: Slash Command
27
- **Signals**: Input starts with `/` (e.g., `/review-pr`, `/write-tests`, `/flow -disable`)
28
- **Action**: Run that command normally. Do NOT trigger the flow.
26
+ | Category | Signals | Action |
27
+ |----------|---------|--------|
28
+ | Slash Command | Input starts with `/` | Run that command normally. Do NOT trigger the flow. |
29
+ | Question/Exploration | Asking about code, explanations, help | Answer normally. Do NOT trigger the flow. |
30
+ | Trivial Task | Single-file change, obvious fix, complexity 0-2 | Execute directly. Do NOT trigger the flow. |
31
+ | **Feature Request** | New functionality, behavior changes, multi-file scope, complexity 3+ | **TRIGGER THE FULL FLOW BELOW. You MUST complete ALL 6 steps in order.** |
29
32
 
30
- ### Category 2: Question or Exploration
31
- **Signals**: User is asking about code, requesting explanations, exploring the codebase, or asking for help.
32
- **Examples**: "What does this function do?", "How does auth work here?", "Show me the API routes"
33
- **Action**: Answer normally. Do NOT trigger the flow.
34
-
35
- ### Category 3: Trivial Task
36
- **Signals**: Single-file change, obvious fix, user specifies exact change, no architectural decisions needed. Estimated complexity 0-2.
37
- **Examples**: "Fix the typo in README", "Rename this variable to camelCase", "Add a missing import"
38
- **Action**: Execute directly. Do NOT trigger the flow.
33
+ ### When Uncertain
39
34
 
40
- ### Category 4: Feature Request
41
- **Signals**: Adding new functionality, behavior changes, multi-file scope, mentions creating/building/implementing, references APIs/integrations/components. Estimated complexity 3+.
42
- **Examples**: "Add dark mode support", "Implement user authentication", "Create a new API endpoint for payments"
43
- **Action**: **Trigger the full flow** (see below).
35
+ If the input doesn't clearly fit a category, **CALL** `AskQuestion` to ask:
44
36
 
45
- ### When Uncertain
46
- If the input doesn't clearly fit a category, use the `AskUserQuestion` tool:
47
-
48
- ```typescript
49
- AskUserQuestion({
50
- questions: [{
51
- question: "I'm in autopilot mode. How should I handle this request?",
52
- header: "Flow mode",
53
- options: [
54
- { label: "Run full flow", description: "Run the full workflow: discovery → plan → execute → review" },
55
- { label: "Handle directly", description: "Just handle this task directly without the full flow" }
56
- ],
57
- multiSelect: false
58
- }]
59
- })
60
- ```
37
+ - **CALL** `SwitchMode(target_mode_id: "plan", explanation: "Classifying user input for autopilot mode")` — **actually invoke the tool**
38
+ - **CALL** `AskQuestion` with these options:
39
+ - A) Run the full flow (discovery → plan → execute → review)
40
+ - B) Handle it directly without the full flow
41
+ - After the user answers, **CALL** `SwitchMode(target_mode_id: "agent", explanation: "Input classified, returning to Agent mode")` — **actually invoke the tool**
42
+ - If `SwitchMode` or `AskQuestion` tools are not available, fall back to asking as plain text in chat
61
43
 
62
44
  ---
63
45
 
64
- ## Flow Execution Steps
46
+ ## FULL FLOW — 6 MANDATORY STEPS
65
47
 
66
- When a **feature request** is detected, execute these steps in order. At each step, **Read the relevant command file** to load its context, then follow its instructions.
48
+ **CRITICAL**: When a feature request is detected, you MUST execute ALL 6 steps below in order. **Do NOT skip discovery. Do NOT skip planning. Do NOT jump to writing code.**
49
+
50
+ The flow is: **Contracts → Discovery → Plan → Execute → Review → Archive**
51
+
52
+ ---
67
53
 
68
54
  ### Step 1: Check Contracts
69
55
 
70
- Check `flow/contracts/` for any relevant integration contracts. If found, note them for the discovery step.
56
+ Check `flow/contracts/` for any relevant integration contracts. If found, note them for Step 2.
71
57
 
72
- ### Step 2: Discovery
58
+ ---
73
59
 
74
- 1. **Read** the file `.cursor/commands/discovery-plan.md` to load discovery context
75
- 2. Execute the discovery skill following that command's instructions
76
- 3. **PAUSE**: Ask user discovery questions as needed (mandatory checkpoint)
77
- 4. Produce the discovery document in `flow/discovery/`
78
- 5. Write transition summary (see format below)
79
- 6. **Auto-proceed** to Step 3 (override the "ask before proceeding" rule)
60
+ ### Step 2: Discovery (MANDATORY — Do NOT skip)
80
61
 
81
- ### Step 3: Create Plan
62
+ **PURPOSE**: Gather requirements, search the codebase for context, ask clarifying questions. **NO CODE is written in this step.**
82
63
 
83
- **GATE CHECK**: Before proceeding, verify that Step 2 produced a discovery document in `flow/discovery/`. If no discovery document exists, **DO NOT proceed** — go back to Step 2. A plan cannot be created without a discovery document. This is a hard requirement with no exceptions.
64
+ **What to do**:
84
65
 
85
- 1. **Verify** discovery document exists in `flow/discovery/` (created in Step 2)
86
- 2. **Read** the file `.cursor/commands/create-plan.md` to load planning context
87
- 3. Execute the create-plan skill with the discovery document as input
88
- 4. **PAUSE**: Present the plan for user approval (mandatory checkpoint)
89
- 5. Wait for user to approve the plan before proceeding
90
- 6. Produce the plan document in `flow/plans/`
91
- 7. Write transition summary
92
- 8. **Auto-proceed** to Step 4 (override the "no auto-chaining" rule)
66
+ 1. Read the file `.cursor/commands/discovery-plan.md` for detailed instructions
67
+ 2. Search the codebase to find all files related to the feature (components, types, API routes, stores, tests)
68
+ 3. Read referenced documents or contracts if any
69
+ 4. **SWITCH TO PLAN MODE and ask clarifying questions** — this is a mandatory checkpoint:
70
+ - **CALL** `SwitchMode(target_mode_id: "plan", explanation: "Discovery phase: Gathering requirements via interactive questions")` — **actually invoke the tool, do not describe it**
71
+ - **CALL** `AskQuestion` tool for each clarifying question about requirements (use 2-6 options per question, A/B/C/D format)
72
+ - Wait for the user to answer all questions
73
+ - **CALL** `SwitchMode(target_mode_id: "agent", explanation: "Discovery questions complete, returning to Agent mode")` — **actually invoke the tool**
74
+ - If `SwitchMode` or `AskQuestion` tools are not available, fall back to asking questions as plain text in chat
75
+ 5. Document requirements as: Functional (FR-), Non-Functional (NFR-), Constraints (C-)
76
+ 6. Identify technical considerations, risks, and proposed approach (high-level, NO code)
77
+ 7. **Save the discovery document** to `flow/discovery/discovery_<feature>_v1.md`
93
78
 
94
- ### Step 4: Execute Plan
79
+ **Output**: A discovery markdown file in `flow/discovery/`
95
80
 
96
- 1. **Read** the file `.cursor/commands/execute-plan.md` to load execution context
97
- 2. Execute the plan following complexity-based grouping strategy
98
- 3. Update the plan file with progress
99
- 4. Run build + test verification at the end
100
- 5. Write transition summary
101
- 6. **Auto-proceed** to Step 5
81
+ **FORBIDDEN during discovery**: Writing code, editing source files, creating plans, running build/test commands
102
82
 
103
- ### Step 5: Review Code
83
+ **After completing discovery**: Auto-proceed to Step 3. Do NOT ask "Would you like to proceed?" — just continue.
104
84
 
105
- 1. **Read** the file `.cursor/commands/review-code.md` to load review context
106
- 2. Review all uncommitted changes
107
- 3. Present the review summary
85
+ ---
108
86
 
109
- ### Step 6: Archive and Complete
87
+ ### Step 3: Create Plan (MANDATORY — Do NOT skip)
110
88
 
111
- 1. Move the discovery document to `flow/archive/`
112
- 2. Move the plan document to `flow/archive/`
113
- 3. Present completion summary
114
- 4. **Prompt for context cleanup** (see below)
89
+ **GATE CHECK**: Before this step, verify that Step 2 produced a discovery document in `flow/discovery/`. **If no discovery document exists, go back to Step 2. A plan CANNOT be created without discovery. No exceptions.**
90
+
91
+ **What to do**:
92
+
93
+ 1. Read the file `.cursor/commands/create-plan.md` for detailed instructions
94
+ 2. Read the discovery document created in Step 2
95
+ 3. Extract requirements (FR, NFR, Constraints) from discovery
96
+ 4. Create phases with complexity scores (0-10) for each phase
97
+ 5. Tests MUST be the last phase
98
+ 6. Include a Key Changes section
99
+ 7. **Save the plan** to `flow/plans/plan_<feature>_v1.md`
100
+ 8. **PAUSE and present the plan for user approval** — this is a mandatory checkpoint
101
+ 9. Wait for user to approve before proceeding
102
+
103
+ **Output**: A plan markdown file in `flow/plans/`
104
+
105
+ **FORBIDDEN during planning**: Writing code, editing source files, running build/test commands
106
+
107
+ **After user approves**: Auto-proceed to Step 4.
115
108
 
116
109
  ---
117
110
 
118
- ## Transition Summary Format
111
+ ### Step 4: Execute Plan
119
112
 
120
- At each step boundary, write this brief summary to bridge context:
113
+ **What to do**:
121
114
 
122
- ```
123
- ## Flow Progress
115
+ 1. Read the file `.cursor/commands/execute-plan.md` for detailed instructions
116
+ 2. Read the plan file created in Step 3
117
+ 3. Execute phases following complexity-based grouping:
118
+ - Combined score ≤ 6: Aggregate phases together
119
+ - Combined score 7-10: Execute 1-2 phases at a time
120
+ - Combined score > 10: Execute one phase at a time
121
+ - Tests phase: Always execute separately
122
+ 4. For each phase: implement the code, then mark tasks complete in the plan file
123
+ 5. **Run build + test verification ONLY at the very end** (not between phases)
124
+ 6. Update the plan file with progress after each phase
124
125
 
125
- **Feature**: [feature name from user input]
126
- **Current Step**: [N] of 6
127
- **Completed**:
128
- - Step 1: Contracts check → [found/none]
129
- - Step 2: Discovery → `flow/discovery/discovery_<feature>_v1.md`
130
- - Step 3: Plan → `flow/plans/plan_<feature>_v1.md`
131
- **Next**: [description of next step]
132
- **Key context**: [1-2 sentences of what matters for the next step]
133
- ```
126
+ **After execution completes**: Auto-proceed to Step 5.
127
+
128
+ ---
129
+
130
+ ### Step 5: Review Code
131
+
132
+ **What to do**:
133
+
134
+ 1. Read the file `.cursor/commands/review-code.md` for detailed instructions
135
+ 2. Review all uncommitted changes (git diff)
136
+ 3. Check for pattern consistency, security issues, and code quality
137
+ 4. Present a review summary
138
+
139
+ **After review**: Auto-proceed to Step 6.
134
140
 
135
141
  ---
136
142
 
137
- ## Context Cleanup Prompt
143
+ ### Step 6: Archive and Complete
138
144
 
139
- After Step 6 completes, always prompt:
145
+ 1. Move the discovery document to `flow/archive/`
146
+ 2. Move the plan document to `flow/archive/`
147
+ 3. Present completion summary:
140
148
 
141
149
  ```
142
150
  Flow complete! All artifacts archived.
143
151
 
144
- **Summary**:
152
+ Summary:
145
153
  - Discovery: archived
146
154
  - Plan: archived
147
155
  - Code: reviewed
148
156
  - Build: passing
149
157
  - Tests: passing
150
158
 
151
- For best results on your next feature, consider starting a fresh context with `/clear`.
152
159
  Ready for the next task?
153
160
  ```
154
161
 
155
162
  ---
156
163
 
164
+ ## Transition Summary Format
165
+
166
+ At each step boundary, write this brief summary:
167
+
168
+ ```
169
+ ## Flow Progress
170
+
171
+ **Feature**: [feature name]
172
+ **Current Step**: [N] of 6
173
+ **Completed**:
174
+ - Step 1: Contracts check → [found/none]
175
+ - Step 2: Discovery → `flow/discovery/discovery_<feature>_v1.md`
176
+ - Step 3: Plan → `flow/plans/plan_<feature>_v1.md`
177
+ **Next**: [description of next step]
178
+ ```
179
+
180
+ ---
181
+
157
182
  ## Mandatory Checkpoints
158
183
 
159
184
  Even in autopilot, these checkpoints **always** pause for user input:
@@ -161,12 +186,10 @@ Even in autopilot, these checkpoints **always** pause for user input:
161
186
  | Checkpoint | When | Why |
162
187
  | --- | --- | --- |
163
188
  | Discovery Q&A | Step 2 | User must answer requirements questions |
164
- | Discovery Gate | Step 2→3 | Discovery document must exist before plan creation. No exceptions. |
165
- | Plan Approval | Step 3 | User must review and approve the plan before execution |
166
-
167
- All other transitions happen automatically.
189
+ | Discovery Gate | Step 2→3 | Discovery document MUST exist before plan. No exceptions. |
190
+ | Plan Approval | Step 3 | User must approve plan before execution begins |
168
191
 
169
- **Hard Rule**: Step 3 (Create Plan) CANNOT start unless Step 2 (Discovery) produced a document in `flow/discovery/`. If the discovery document does not exist, the flow must loop back to Step 2. A plan without discovery is incomplete and will lead to poor implementations.
192
+ All other transitions happen automatically without asking.
170
193
 
171
194
  ---
172
195