planflow-ai 1.0.2 → 1.0.3

package/.claude/commands/create-plan.md

@@ -58,12 +58,19 @@ RELATED COMMANDS:
 
 ---
 
+> ⚠️ **AUTOPILOT MODE CHECK**
+>
+> Before proceeding, check if `flow/.autopilot` exists.
+> - **If YES**: Autopilot is ON. After creating the plan and getting user approval, **auto-proceed** to `/execute-plan` with the plan output. Do NOT wait for manual invocation.
+> - **If NO**: Follow the standard rules below (stop and wait for user).
+
 ## Critical Rules
 
 | Rule                     | Description                                              |
 | ------------------------ | -------------------------------------------------------- |
-| **No Auto-Chaining**     | NEVER auto-invoke /execute-plan - user must invoke it    |
-| **Complete and Stop**    | After presenting results, STOP and wait for user         |
+| **Discovery Required**   | NEVER create a plan without a discovery document. If none exists, run `/discovery-plan` first. No exceptions. |
+| **No Auto-Chaining**     | NEVER auto-invoke /execute-plan - user must invoke it (unless autopilot ON) |
+| **Complete and Stop**    | After presenting results, STOP and wait for user (unless autopilot ON) |
 
 ---
 
@@ -80,18 +87,27 @@ RELATED COMMANDS:
 
 ---
 
-### Step 2: Validate Discovery Phase Completion
+### Step 2: Validate Discovery Phase Completion (HARD BLOCK)
+
+**A discovery document is REQUIRED before creating any plan. No exceptions.**
 
-**Before creating a plan, verify that proper discovery was performed.**
+1. Check user input for a discovery document reference (`@flow/discovery/...`)
+2. If no reference provided, search `flow/discovery/` for a matching discovery document
+3. **If NO discovery document exists**: **STOP immediately.** Do NOT create a plan. Instead:
+   - Inform the user that discovery is required before planning
+   - Invoke `/discovery-plan` to start the discovery process
+   - Example response:
+     ```
+     A discovery document is required before creating a plan. Discovery refines your idea,
+     gathers requirements, and identifies risks — skipping it leads to incomplete plans.
 
-1. Check user input for discovery indicators:
-   - Discovery document reference (`@flow/discovery/...`)
-   - FR/NFR prefixes in requirements
-2. Check the discovery folder for a matching document in `flow/discovery/`
-3. If NO discovery indicators found: Recommend `/discovery-plan` command first
-4. If discovery indicators ARE found: Proceed with plan creation
+     Starting discovery now...
+     ```
+   - Then run the discovery process for the user's feature
+4. If a discovery document IS found: Proceed with plan creation using that document
 
 **Important**: NEVER read or reference files in `flow/archive/` - these are outdated.
+**Important**: NEVER create a plan without a discovery document. This rule has NO exceptions.
 
 ---
 
@@ -138,7 +154,9 @@ Plan Created!
 3. When ready, invoke `/execute-plan @flow/plans/plan_<feature>_v<version>.md`
 ```
 
-**CRITICAL**: This command is now complete. Do NOT auto-invoke `/execute-plan`. Wait for the user to explicitly invoke it.
+**CRITICAL**: If autopilot mode is OFF (`flow/.autopilot` does not exist), this command is now complete. Do NOT auto-invoke `/execute-plan`. Wait for the user to explicitly invoke it.
+
+**If autopilot mode is ON** (`flow/.autopilot` exists): Auto-proceed to `/execute-plan` with the plan file after the user approves the plan.
 
 ---
 

package/.claude/commands/discovery-plan.md

@@ -12,15 +12,21 @@ This command creates a discovery document for gathering and clarifying requireme
 
 ---
 
+> ⚠️ **AUTOPILOT MODE CHECK**
+>
+> Before proceeding, check if `flow/.autopilot` exists.
+> - **If YES**: Autopilot is ON. After completing discovery and user Q&A, **auto-proceed** to `/create-plan` with the discovery output. Do NOT ask "Would you like to proceed?" - just continue.
+> - **If NO**: Follow the standard rules below (stop and wait for user).
+
 > ⚠️ **IMPORTANT - DISCOVERY ONLY**
 >
 > This command ONLY creates a discovery document. It does NOT:
 > - Create implementation plans (use `/create-plan` for that)
 > - Execute code or implementation steps (use `/execute-plan` for that)
 > - Write any source code files
-> - Auto-chain to the next command
+> - Auto-chain to the next command (unless autopilot mode is ON)
 >
-> After creating the discovery document, the command STOPS and waits for user review.
+> After creating the discovery document, the command STOPS and waits for user review (unless autopilot mode is ON).
 
 ---
 
@@ -85,8 +91,8 @@ These rules are mandatory. For detailed patterns and guidelines, see `.claude/ru
 | **Read First**           | Read all referenced documents before asking questions    |
 | **High-Level Only**      | Technical considerations are conceptual, not code        |
 | **Allow Refinement**     | User reviews and refines discovery before plan creation  |
-| **Ask Before Proceeding**| ASK user if they want to proceed to /create-plan         |
-| **No Auto-Execution**    | Do NOT auto-invoke commands without user confirmation    |
+| **Ask Before Proceeding**| ASK user if they want to proceed to /create-plan (unless autopilot ON) |
+| **No Auto-Execution**    | Do NOT auto-invoke commands without user confirmation (unless autopilot ON) |
 | **NO PLANNING**          | Do NOT create implementation plans during discovery      |
 | **NO EXECUTION**         | Do NOT execute any implementation steps                  |
 
@@ -177,14 +183,21 @@ Discovery Complete!
 3. Proceed to planning when ready
 ```
 
-**Now ask the user**:
-
-```markdown
-Would you like me to proceed with creating the implementation plan?
-
-- **Yes**: I'll invoke `/create-plan @flow/discovery/discovery_<feature>_v1.md`
-- **No**: You can review the discovery and invoke `/create-plan` when ready
-- **Refine first**: Let me know what needs to be adjusted in the discovery
+**Now ask the user using the `AskUserQuestion` tool**:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    question: "Would you like me to proceed with creating the implementation plan?",
+    header: "Next step",
+    options: [
+      { label: "Yes, create plan", description: "I'll invoke /create-plan with the discovery document" },
+      { label: "No, review first", description: "You can review the discovery and invoke /create-plan when ready" },
+      { label: "Refine discovery", description: "Let me know what needs to be adjusted in the discovery" }
+    ],
+    multiSelect: false
+  }]
+})
 ```
 
 ⚠️ **WAIT for user response before proceeding**

package/.claude/commands/execute-plan.md

@@ -73,13 +73,19 @@ RELATED COMMANDS:
 
 ---
 
+> ⚠️ **AUTOPILOT MODE CHECK**
+>
+> Before proceeding, check if `flow/.autopilot` exists.
+> - **If YES**: Autopilot is ON. After completing execution (build + test pass), **auto-proceed** to `/review-code`. Do NOT stop and wait.
+> - **If NO**: Follow the standard rules below (stop and wait for user).
+
 ## Critical Rules
 
 | Rule                     | Description                                              |
 | ------------------------ | -------------------------------------------------------- |
 | **Build ONLY at End**    | Do NOT run build after each phase - only at the very end |
 | **No Direct DB/ORM**     | NEVER run ORM or database commands directly              |
-| **Complete and Stop**    | After execution, STOP and wait for user                  |
+| **Complete and Stop**    | After execution, STOP and wait for user (unless autopilot ON) |
 
 ---
 
@@ -182,7 +188,7 @@ After the skill completes:
 
 1. Present summary of all changes made
 2. Confirm all tests pass
-3. Ask if the plan should be archived:
+3. Ask if the plan should be archived using the `AskUserQuestion` tool:
 
 ```markdown
 Execution Complete!
@@ -191,14 +197,20 @@ Execution Complete!
 - X phases completed
 - All tests passing
 - Build successful
-
-**Archive the plan?**
-This will move the plan to `flow/archive/`:
-```bash
-mv flow/plans/plan_<feature>_v1.md flow/archive/
 ```
 
-Would you like to archive this plan?
+```typescript
+AskUserQuestion({
+  questions: [{
+    question: "Would you like to archive this completed plan?",
+    header: "Archive",
+    options: [
+      { label: "Yes, archive it", description: "Move the plan to flow/archive/ - recommended for completed plans" },
+      { label: "No, keep it", description: "Keep the plan in flow/plans/ for reference" }
+    ],
+    multiSelect: false
+  }]
+})
 ```
 
 ---
@@ -566,10 +578,20 @@ npm run build && npm run test
 
 4. **List all key changes** made
 
-5. **Ask if the plan should be archived**:
-
-```bash
-mv flow/plans/plan_feature_name_v1.md flow/archive/
+5. **Ask if the plan should be archived** using the `AskUserQuestion` tool:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    question: "Would you like to archive this completed plan?",
+    header: "Archive",
+    options: [
+      { label: "Yes, archive it", description: "Move the plan to flow/archive/" },
+      { label: "No, keep it", description: "Keep the plan in flow/plans/" }
+    ],
+    multiSelect: false
+  }]
+})
 ```
 
 ---

package/.claude/commands/flow.md

@@ -0,0 +1,105 @@
+---
+description: Toggle autopilot flow mode - automatically orchestrates discovery, planning, execution, and review for feature requests
+---
+
+# Flow: Autopilot Mode Toggle
+
+## Command Description
+
+This command enables or disables **autopilot flow mode**. When enabled, every new user input is automatically classified and, if it's a feature request, the full plan-flow workflow runs automatically:
+
+**contracts check → discovery → plan → execute → review-code → archive**
+
+The LLM pauses only at mandatory checkpoints (discovery Q&A, plan approval).
+
+---
+
+## Help
+
+**If the user invokes this command with `-help`, display only this section and stop:**
+
+```
+/flow - Autopilot Flow Mode Toggle
+
+DESCRIPTION:
+  Enables or disables autopilot flow mode. When enabled, feature requests
+  automatically run the full plan-flow workflow without manual command invocation.
+
+USAGE:
+  /flow -enable       Enable autopilot mode (persists across sessions)
+  /flow -disable      Disable autopilot mode
+  /flow -status       Show current autopilot state
+  /flow               Same as -status
+  /flow -help         Show this help
+
+BEHAVIOR WHEN ENABLED:
+  - Feature requests → full flow (discovery → plan → execute → review → archive)
+  - Trivial tasks (complexity 0-2) → executed directly, no flow
+  - Questions/exploration → answered normally
+  - Slash commands → run as normal
+
+MANDATORY CHECKPOINTS (even in autopilot):
+  - Discovery phase: pauses for user Q&A
+  - Plan review: pauses for user approval before execution
+
+CONTEXT MANAGEMENT:
+  - Only loads the relevant command context at each step
+  - Suggests context cleanup (/clear) after each completed flow cycle
+
+STATE:
+  Persisted in flow/.autopilot (survives session restarts)
+```
+
+---
+
+## Instructions
+
+### When invoked with `-enable`
+
+1. Create the file `flow/.autopilot` (empty file)
+2. Confirm to the user:
+
+```markdown
+Autopilot flow mode **enabled**.
+
+From now on, feature requests will automatically run the full workflow:
+1. Check contracts → 2. Discovery (pause for Q&A) → 3. Create plan (pause for approval) → 4. Execute plan → 5. Review code → 6. Archive
+
+Trivial tasks and questions are handled normally without the flow.
+
+Use `/flow -disable` to turn off, or `/flow -status` to check state.
+```
+
+### When invoked with `-disable`
+
+1. Delete the file `flow/.autopilot` (if it exists)
+2. Confirm to the user:
+
+```markdown
+Autopilot flow mode **disabled**.
+
+Commands will no longer auto-chain. Use individual slash commands as before:
+`/discovery-plan` → `/create-plan` → `/execute-plan` → `/review-code`
+```
+
+### When invoked with `-status` or no arguments
+
+1. Check if `flow/.autopilot` exists
+2. Report:
+
+```markdown
+Autopilot flow mode: **[ENABLED/DISABLED]**
+
+[If enabled]: Feature requests will automatically run the full workflow.
+[If disabled]: Use individual slash commands to run each step manually.
+```
+
+---
+
+## Critical Rules
+
+| Rule | Description |
+| --- | --- |
+| **File-based state** | State is stored in `flow/.autopilot` - create to enable, delete to disable |
+| **No other side effects** | This command ONLY manages the marker file. It does not run any workflow steps. |
+| **Complete and stop** | After toggling state, STOP and wait for user input |

package/.claude/commands/review-code.md

@@ -62,12 +62,18 @@ RELATED COMMANDS:
 
 ---
 
+> ⚠️ **AUTOPILOT MODE CHECK**
+>
+> Before proceeding, check if `flow/.autopilot` exists.
+> - **If YES**: Autopilot is ON. After completing the review, **auto-archive** the discovery and plan documents to `flow/archive/`, present the completion summary, and prompt for context cleanup (`/clear`).
+> - **If NO**: Follow the standard rules below (stop and wait for user).
+
 ## Critical Rules
 
 | Rule                     | Description                                              |
 | ------------------------ | -------------------------------------------------------- |
 | **Read-Only Analysis**   | This command ONLY produces a review document             |
-| **Complete and Stop**    | After presenting results, STOP and wait for user         |
+| **Complete and Stop**    | After presenting results, STOP and wait for user (unless autopilot ON) |
 
 ---
 

package/.claude/rules/core/autopilot-mode.md

@@ -0,0 +1,188 @@
+# Autopilot Flow Mode
+
+## Purpose
+
+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.
+
+---
+
+## On Session Start
+
+1. Check if `flow/.autopilot` exists
+2. If it exists: autopilot mode is **ON** - follow the rules below for every user input
+3. If it does not exist: autopilot mode is **OFF** - ignore this rule entirely, normal behavior applies
+
+---
+
+## Input Classification
+
+When autopilot is ON, classify every new user input before acting:
+
+### Category 1: Slash Command
+**Signals**: Input starts with `/` (e.g., `/review-pr`, `/write-tests`, `/flow -disable`)
+**Action**: Run that command normally. Do NOT trigger the flow.
+
+### Category 2: Question or Exploration
+**Signals**: User is asking about code, requesting explanations, exploring the codebase, or asking for help.
+**Examples**: "What does this function do?", "How does auth work here?", "Show me the API routes"
+**Action**: Answer normally. Do NOT trigger the flow.
+
+### Category 3: Trivial Task
+**Signals**: Single-file change, obvious fix, user specifies exact change, no architectural decisions needed. Estimated complexity 0-2.
+**Examples**: "Fix the typo in README", "Rename this variable to camelCase", "Add a missing import"
+**Action**: Execute directly. Do NOT trigger the flow.
+
+### Category 4: Feature Request
+**Signals**: Adding new functionality, behavior changes, multi-file scope, mentions creating/building/implementing, references APIs/integrations/components. Estimated complexity 3+.
+**Examples**: "Add dark mode support", "Implement user authentication", "Create a new API endpoint for payments"
+**Action**: **Trigger the full flow** (see below).
+
+### When Uncertain
+If the input doesn't clearly fit a category, use the `AskUserQuestion` tool:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    question: "I'm in autopilot mode. How should I handle this request?",
+    header: "Flow mode",
+    options: [
+      { label: "Run full flow", description: "Run the full workflow: discovery → plan → execute → review" },
+      { label: "Handle directly", description: "Just handle this task directly without the full flow" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+---
+
+## Flow Execution Steps
+
+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.
+
+### Step 1: Check Contracts
+
+Check `flow/contracts/` for any relevant integration contracts. If found, note them for the discovery step.
+
+### Step 2: Discovery
+
+1. **Read** the file `.claude/commands/discovery-plan.md` to load discovery context
+2. Execute the discovery skill following that command's instructions
+3. **PAUSE**: Ask user discovery questions as needed (mandatory checkpoint)
+4. Produce the discovery document in `flow/discovery/`
+5. Write transition summary (see format below)
+6. **Auto-proceed** to Step 3 (override the "ask before proceeding" rule)
+
+### Step 3: Create Plan
+
+**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.
+
+1. **Verify** discovery document exists in `flow/discovery/` (created in Step 2)
+2. **Read** the file `.claude/commands/create-plan.md` to load planning context
+3. Execute the create-plan skill with the discovery document as input
+4. **PAUSE**: Present the plan for user approval (mandatory checkpoint)
+5. Wait for user to approve the plan before proceeding
+6. Produce the plan document in `flow/plans/`
+7. Write transition summary
+8. **Auto-proceed** to Step 4 (override the "no auto-chaining" rule)
+
+### Step 4: Execute Plan
+
+1. **Read** the file `.claude/commands/execute-plan.md` to load execution context
+2. Execute the plan following complexity-based grouping strategy
+3. Update the plan file with progress
+4. Run build + test verification at the end
+5. Write transition summary
+6. **Auto-proceed** to Step 5
+
+### Step 5: Review Code
+
+1. **Read** the file `.claude/commands/review-code.md` to load review context
+2. Review all uncommitted changes
+3. Present the review summary
+
+### Step 6: Archive and Complete
+
+1. Move the discovery document to `flow/archive/`
+2. Move the plan document to `flow/archive/`
+3. Present completion summary
+4. **Prompt for context cleanup** (see below)
+
+---
+
+## Transition Summary Format
+
+At each step boundary, write this brief summary to bridge context:
+
+```
+## Flow Progress
+
+**Feature**: [feature name from user input]
+**Current Step**: [N] of 6
+**Completed**:
+- Step 1: Contracts check → [found/none]
+- Step 2: Discovery → `flow/discovery/discovery_<feature>_v1.md`
+- Step 3: Plan → `flow/plans/plan_<feature>_v1.md`
+**Next**: [description of next step]
+**Key context**: [1-2 sentences of what matters for the next step]
+```
+
+---
+
+## Context Cleanup Prompt
+
+After Step 6 completes, always prompt:
+
+```
+Flow complete! All artifacts archived.
+
+**Summary**:
+- Discovery: archived
+- Plan: archived
+- Code: reviewed
+- Build: passing
+- Tests: passing
+
+For best results on your next feature, consider starting a fresh context with `/clear`.
+Ready for the next task?
+```
+
+---
+
+## Mandatory Checkpoints
+
+Even in autopilot, these checkpoints **always** pause for user input:
+
+| Checkpoint | When | Why |
+| --- | --- | --- |
+| Discovery Q&A | Step 2 | User must answer requirements questions |
+| Discovery Gate | Step 2→3 | Discovery document must exist before plan creation. No exceptions. |
+| Plan Approval | Step 3 | User must review and approve the plan before execution |
+
+All other transitions happen automatically.
+
+**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.
+
+---
+
+## Overriding No Auto-Chaining Rules
+
+When autopilot is ON, the following rules in individual commands are **suspended**:
+
+- `discovery-plan.md`: "Ask Before Proceeding" and "No Auto-Execution" rules
+- `create-plan.md`: "No Auto-Chaining" and "Complete and Stop" rules
+- `execute-plan.md`: "Complete and Stop" rule
+- `review-code.md`: completion stop behavior
+
+These rules remain fully active when autopilot is OFF.
+
+---
+
+## Error Handling
+
+If any step fails:
+
+1. Present the error to the user
+2. Ask how to proceed: retry, skip, or abort the flow
+3. If aborted: note which steps completed and which artifacts exist
+4. The flow can be resumed manually using individual slash commands

package/.claude/rules/patterns/plans-patterns.md

@@ -34,9 +34,9 @@ All implementation plans must be created inside `flow/plans/` using snake_case n
 
 ---
 
-### 2. Use Discovery Folder for Research
+### 2. Discovery is Required Before Planning
 
-Before creating a plan for complex features, create discovery documents in `flow/discovery/`. See `.claude/rules/patterns/discovery-patterns.md` for details.
+A discovery document in `flow/discovery/` is **required** before creating any plan. Plans cannot be created without a completed discovery document. If no discovery exists, run `/discovery-plan` first. No exceptions. See `.claude/rules/patterns/discovery-patterns.md` for details.
 
 ---
 

package/README.md

@@ -99,9 +99,12 @@ Copy `skills/plan-flow/` to your project's `skills/plan-flow/`
 | `/review-code` | Review local uncommitted changes |
 | `/review-pr` | Review a Pull Request |
 | `/write-tests` | Generate tests for coverage target |
+| `/flow` | Toggle autopilot mode on/off |
 
 ## Workflow
 
+### Manual (default)
+
 ```
 1. /setup           -> Index project patterns (run once)
 2. /discovery-plan  -> Gather requirements for a feature
@@ -110,6 +113,35 @@ Copy `skills/plan-flow/` to your project's `skills/plan-flow/`
 5. /review-code     -> Review changes before committing
 ```
 
+### Autopilot Mode
+
+Enable autopilot with `/flow -enable` and the full workflow runs automatically for feature requests:
+
+```
+You: "Add dark mode support"
+
+  -> Contracts check (automatic)
+  -> Discovery (pauses for your Q&A)
+  -> Create plan (pauses for your approval)
+  -> Execute plan (automatic)
+  -> Review code (automatic)
+  -> Archive (automatic)
+```
+
+Autopilot classifies every input and only triggers the full flow for feature requests (complexity 3+). Questions, trivial tasks, and slash commands are handled normally.
+
+| Usage | Description |
+|-------|-------------|
+| `/flow -enable` | Enable autopilot mode |
+| `/flow -disable` | Disable autopilot mode |
+| `/flow -status` | Check current state |
+
+**Mandatory checkpoints** — even in autopilot, the flow always pauses for:
+- **Discovery Q&A**: You answer requirements questions
+- **Plan approval**: You review and approve the plan before execution
+
+State is persisted in `flow/.autopilot` (survives session restarts).
+
 ## Complexity Scoring
 
 Every plan phase has a complexity score (0-10):
@@ -134,7 +166,8 @@ flow/
 ├── plans/             # Active implementation plans
 ├── references/        # Reference materials
 ├── reviewed-code/     # Code review documents
-└── reviewed-pr/       # PR review documents
+├── reviewed-pr/       # PR review documents
+└── ledger.md          # Persistent project learning journal
 ```
 
 ## Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planflow-ai",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Structured AI-assisted development workflows for discovery, planning, execution, code reviews, and testing",
   "type": "module",
   "main": "dist/cli/index.js",

package/rules/core/_index.mdc

@@ -9,8 +9,8 @@ alwaysApply: false
 
 Core rules define the foundational coding standards that apply across the entire project. These include best practices to follow (allowed patterns), anti-patterns to avoid (forbidden patterns), and complexity scoring for implementation planning.
 
-**Total Files**: 4 files, ~833 lines
-**Reference Codes**: COR-AP-1 through COR-LDG-2
+**Total Files**: 5 files, ~1011 lines
+**Reference Codes**: COR-AP-1 through COR-AM-3
 
 ---
 
@@ -40,6 +40,14 @@ Core rules define the foundational coding standards that apply across the entire
 | COR-CS-4 | Common complexity patterns table | complexity-scoring.mdc | 168-185 |
 | COR-CS-5 | Real-world scoring examples | complexity-scoring.mdc | 187-236 |
 
+### Autopilot Mode (`autopilot-mode.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| COR-AM-1 | Input classification (slash commands, questions, trivial, feature requests) | autopilot-mode.mdc | 18-50 |
+| COR-AM-2 | Flow execution steps (contracts, discovery, plan, execute, review, archive) | autopilot-mode.mdc | 52-110 |
+| COR-AM-3 | Mandatory checkpoints and overriding rules | autopilot-mode.mdc | 140-178 |
+
 ### Project Ledger (`project-ledger.mdc`)
 
 | Code | Description | Source | Lines |
@@ -64,6 +72,9 @@ Core rules define the foundational coding standards that apply across the entire
 | COR-CS-5 | Need detailed scoring examples |
 | COR-LDG-1 | Need ledger behavior and entry guidelines |
 | COR-LDG-2 | Need ledger maintenance and integration rules |
+| COR-AM-1 | Need to understand input classification for autopilot |
+| COR-AM-2 | Need autopilot flow execution steps |
+| COR-AM-3 | Need mandatory checkpoint and override rules |
 
 ---
 
@@ -97,3 +108,4 @@ Core rules define the foundational coding standards that apply across the entire
 - `allowed-patterns.mdc` and `forbidden-patterns.mdc` have `alwaysApply: true` - they are loaded automatically by Cursor
 - `project-ledger.mdc` has `alwaysApply: true` - maintains persistent project memory
 - `complexity-scoring.mdc` is loaded on-demand when needed for planning
+- `autopilot-mode.mdc` has `alwaysApply: true` - detects and orchestrates autopilot flow mode

package/rules/core/autopilot-mode.mdc

@@ -0,0 +1,193 @@
+---
+description: "Autopilot flow mode - when flow/.autopilot exists, automatically orchestrates discovery → plan → execute → review for feature requests"
+alwaysApply: true
+---
+
+# Autopilot Flow Mode
+
+## Purpose
+
+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.
+
+---
+
+## On Session Start
+
+1. Check if `flow/.autopilot` exists
+2. If it exists: autopilot mode is **ON** - follow the rules below for every user input
+3. If it does not exist: autopilot mode is **OFF** - ignore this rule entirely, normal behavior applies
+
+---
+
+## Input Classification
+
+When autopilot is ON, classify every new user input before acting:
+
+### Category 1: Slash Command
+**Signals**: Input starts with `/` (e.g., `/review-pr`, `/write-tests`, `/flow -disable`)
+**Action**: Run that command normally. Do NOT trigger the flow.
+
+### Category 2: Question or Exploration
+**Signals**: User is asking about code, requesting explanations, exploring the codebase, or asking for help.
+**Examples**: "What does this function do?", "How does auth work here?", "Show me the API routes"
+**Action**: Answer normally. Do NOT trigger the flow.
+
+### Category 3: Trivial Task
+**Signals**: Single-file change, obvious fix, user specifies exact change, no architectural decisions needed. Estimated complexity 0-2.
+**Examples**: "Fix the typo in README", "Rename this variable to camelCase", "Add a missing import"
+**Action**: Execute directly. Do NOT trigger the flow.
+
+### Category 4: Feature Request
+**Signals**: Adding new functionality, behavior changes, multi-file scope, mentions creating/building/implementing, references APIs/integrations/components. Estimated complexity 3+.
+**Examples**: "Add dark mode support", "Implement user authentication", "Create a new API endpoint for payments"
+**Action**: **Trigger the full flow** (see below).
+
+### When Uncertain
+If the input doesn't clearly fit a category, use the `AskUserQuestion` tool:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    question: "I'm in autopilot mode. How should I handle this request?",
+    header: "Flow mode",
+    options: [
+      { label: "Run full flow", description: "Run the full workflow: discovery → plan → execute → review" },
+      { label: "Handle directly", description: "Just handle this task directly without the full flow" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+---
+
+## Flow Execution Steps
+
+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.
+
+### Step 1: Check Contracts
+
+Check `flow/contracts/` for any relevant integration contracts. If found, note them for the discovery step.
+
+### Step 2: Discovery
+
+1. **Read** the discovery command to load discovery context
+2. Execute the discovery skill following that command's instructions
+3. **PAUSE**: Ask user discovery questions as needed (mandatory checkpoint)
+4. Produce the discovery document in `flow/discovery/`
+5. Write transition summary (see format below)
+6. **Auto-proceed** to Step 3 (override the "ask before proceeding" rule)
+
+### Step 3: Create Plan
+
+**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.
+
+1. **Verify** discovery document exists in `flow/discovery/` (created in Step 2)
+2. **Read** the create-plan command to load planning context
+3. Execute the create-plan skill with the discovery document as input
+4. **PAUSE**: Present the plan for user approval (mandatory checkpoint)
+5. Wait for user to approve the plan before proceeding
+6. Produce the plan document in `flow/plans/`
+7. Write transition summary
+8. **Auto-proceed** to Step 4 (override the "no auto-chaining" rule)
+
+### Step 4: Execute Plan
+
+1. **Read** the execute-plan command to load execution context
+2. Execute the plan following complexity-based grouping strategy
+3. Update the plan file with progress
+4. Run build + test verification at the end
+5. Write transition summary
+6. **Auto-proceed** to Step 5
+
+### Step 5: Review Code
+
+1. **Read** the review-code command to load review context
+2. Review all uncommitted changes
+3. Present the review summary
+
+### Step 6: Archive and Complete
+
+1. Move the discovery document to `flow/archive/`
+2. Move the plan document to `flow/archive/`
+3. Present completion summary
+4. **Prompt for context cleanup** (see below)
+
+---
+
+## Transition Summary Format
+
+At each step boundary, write this brief summary to bridge context:
+
+```
+## Flow Progress
+
+**Feature**: [feature name from user input]
+**Current Step**: [N] of 6
+**Completed**:
+- Step 1: Contracts check → [found/none]
+- Step 2: Discovery → `flow/discovery/discovery_<feature>_v1.md`
+- Step 3: Plan → `flow/plans/plan_<feature>_v1.md`
+**Next**: [description of next step]
+**Key context**: [1-2 sentences of what matters for the next step]
+```
+
+---
+
+## Context Cleanup Prompt
+
+After Step 6 completes, always prompt:
+
+```
+Flow complete! All artifacts archived.
+
+**Summary**:
+- Discovery: archived
+- Plan: archived
+- Code: reviewed
+- Build: passing
+- Tests: passing
+
+For best results on your next feature, consider starting a fresh context with `/clear`.
+Ready for the next task?
+```
+
+---
+
+## Mandatory Checkpoints
+
+Even in autopilot, these checkpoints **always** pause for user input:
+
+| Checkpoint | When | Why |
+| --- | --- | --- |
+| Discovery Q&A | Step 2 | User must answer requirements questions |
+| Discovery Gate | Step 2→3 | Discovery document must exist before plan creation. No exceptions. |
+| Plan Approval | Step 3 | User must review and approve the plan before execution |
+
+All other transitions happen automatically.
+
+**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.
+
+---
+
+## Overriding No Auto-Chaining Rules
+
+When autopilot is ON, the following rules in individual commands are **suspended**:
+
+- Discovery command: "Ask Before Proceeding" and "No Auto-Execution" rules
+- Create-plan command: "No Auto-Chaining" and "Complete and Stop" rules
+- Execute-plan command: "Complete and Stop" rule
+- Review-code command: completion stop behavior
+
+These rules remain fully active when autopilot is OFF.
+
+---
+
+## Error Handling
+
+If any step fails:
+
+1. Present the error to the user
+2. Ask how to proceed: retry, skip, or abort the flow
+3. If aborted: note which steps completed and which artifacts exist
+4. The flow can be resumed manually using individual slash commands

package/rules/patterns/plans-patterns.mdc

@@ -46,9 +46,9 @@ All implementation plans must be created inside `flow/plans/` using snake_case n
 
 ---
 
-### 2. Use Discovery Folder for Research
+### 2. Discovery is Required Before Planning
 
-Before creating a plan for complex features, create discovery documents in `flow/discovery/`. See `.cursor/rules/patterns/discovery-patterns.mdc` for details.
+A discovery document in `flow/discovery/` is **required** before creating any plan. Plans cannot be created without a completed discovery document. If no discovery exists, run `/discovery-plan` first. No exceptions. See `.cursor/rules/patterns/discovery-patterns.mdc` for details.
 
 ---
 

package/rules/skills/create-plan-skill.mdc

@@ -57,7 +57,7 @@ This skill is **strictly for creating plan documents**. The process:
 
 | Input                | Required | Description                                        |
 | -------------------- | -------- | -------------------------------------------------- |
-| `discovery_document` | Optional | Path to discovery document (recommended)           |
+| `discovery_document` | **Required** | Path to discovery document. Plans cannot be created without one. |
 | `feature_name`       | Yes      | Name of the feature to plan                        |
 | `requirements`       | Optional | Direct requirements if no discovery document       |
 | `version`            | Optional | Version number (auto-incremented if not provided)  |
@@ -66,19 +66,16 @@ This skill is **strictly for creating plan documents**. The process:
 
 ## Workflow
 
-### Step 1: Extract Requirements
+### Step 1: Validate Discovery Document (HARD BLOCK)
 
-**If discovery document was provided**:
+**A discovery document is REQUIRED. No exceptions.**
 
-1. Read the discovery document
-2. Extract feature name, description, goals from the document
-3. Extract FR, NFR, Constraints
-4. Note any risks identified
-
-**If no discovery document**:
-
-1. Use requirements provided directly
-2. Note that discovery was skipped
+1. Check if a discovery document was provided or exists in `flow/discovery/`
+2. **If NO discovery document exists**: **STOP immediately.** Do NOT create a plan. Inform the user that discovery is required and run `/discovery-plan` first.
+3. **If discovery document exists**: Read it and extract:
+   - Feature name, description, goals
+   - FR, NFR, Constraints
+   - Risks identified
 
 ---
 
@@ -254,7 +251,7 @@ Before completing the plan, verify:
 - [ ] All phases have complexity scores (X/10)
 - [ ] Tests are the LAST phase
 - [ ] Key Changes section is populated
-- [ ] Discovery document is referenced (or noted as skipped)
+- [ ] Discovery document is referenced (discovery is required, never skipped)
 - [ ] **NO implementation code is included**
 - [ ] **NO source files were created or modified**
 

package/skills/plan-flow/SKILL.md

@@ -22,6 +22,7 @@ A comprehensive skill set for AI-assisted software development with structured w
 | `/review-code` | Review local uncommitted changes |
 | `/review-pr` | Review a Pull Request |
 | `/write-tests` | Write tests to achieve coverage target |
+| `/flow` | Toggle autopilot mode (auto-chains the full workflow) |
 
 ## Always-Active Features
 
@@ -83,7 +84,7 @@ flow/
 ## Critical Rules
 
 1. **Automated Workflow**: Run discovery → plan → execute automatically. Only stop to ask when you need information from the user.
-2. **Discovery First**: Always run `/discovery` before `/create-plan` for new features or bugs.
+2. **Discovery First (Hard Block)**: `/discovery` is **required** before `/create-plan`. Plans cannot be created without a discovery document. No exceptions. If no discovery exists, run discovery first.
 3. **Tests Last**: Tests are always the last phase of any implementation plan.
 4. **Build at End Only**: Run build verification only after ALL phases complete.
 5. **Archive When Done**: Move completed discovery and plans to `flow/archive/`.

package/skills/plan-flow/flow/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: flow
+description: Toggle autopilot flow mode - automatically orchestrates discovery, planning, execution, and review for feature requests
+metadata: {"openclaw":{"requires":{"bins":["git"]}}}
+user-invocable: true
+---
+
+# Flow: Autopilot Mode Toggle
+
+Enables or disables autopilot flow mode. When enabled, feature requests automatically run the full plan-flow workflow without manual command invocation.
+
+## Usage
+
+```
+/flow -enable       Enable autopilot mode
+/flow -disable      Disable autopilot mode
+/flow -status       Show current state
+/flow               Same as -status
+/flow -help         Show help
+```
+
+## How It Works
+
+**State**: Stored in `flow/.autopilot` (empty marker file). Create to enable, delete to disable.
+
+### When Enabled
+
+Every user input is classified:
+
+| Category | Signals | Action |
+|----------|---------|--------|
+| Slash Command | Starts with `/` | Run normally, no flow |
+| Question/Exploration | Asking about code, explanations | Answer normally, no flow |
+| Trivial Task | Single-file, obvious fix, complexity 0-2 | Execute directly, no flow |
+| Feature Request | New functionality, multi-file, complexity 3+ | **Trigger full flow** |
+
+### Full Flow (6 Steps)
+
+1. **Check Contracts** → Look for relevant integration contracts
+2. **Discovery** (PAUSE) → Gather requirements, ask user questions
+3. **Create Plan** (PAUSE) → Create implementation plan, get user approval
+4. **Execute Plan** → Implement phases with complexity-based grouping
+5. **Review Code** → Review all uncommitted changes
+6. **Archive** → Move artifacts to `flow/archive/`, prompt for cleanup
+
+### Mandatory Checkpoints
+
+Even in autopilot, these always pause for user input:
+
+| Checkpoint | When | Why |
+|------------|------|-----|
+| Discovery Q&A | Step 2 | User must answer requirements questions |
+| Discovery Gate | Step 2→3 | Discovery document must exist before plan. No exceptions. |
+| Plan Approval | Step 3 | User must approve plan before execution |
+
+### When Disabled
+
+Commands run individually as normal:
+`/discovery` → `/create-plan` → `/execute-plan` → `/review-code`
+
+## Toggle Commands
+
+### Enable
+1. Create `flow/.autopilot` (empty file)
+2. Confirm to user that autopilot is enabled
+
+### Disable
+1. Delete `flow/.autopilot`
+2. Confirm to user that autopilot is disabled
+
+### Status
+1. Check if `flow/.autopilot` exists
+2. Report current state (ENABLED/DISABLED)
+
+## Critical Rules
+
+| Rule | Description |
+|------|-------------|
+| **File-based state** | State is stored in `flow/.autopilot` - create to enable, delete to disable |
+| **No other side effects** | This command ONLY manages the marker file. It does not run any workflow steps. |
+| **Complete and stop** | After toggling state, STOP and wait for user input |

package/templates/shared/AGENTS.md.template

@@ -12,6 +12,7 @@
 | `/review-code` | Review local uncommitted changes |
 | `/review-pr` | Review a Pull Request |
 | `/write-tests` | Write tests to achieve coverage target |
+| `/flow` | Toggle autopilot mode (auto-chains discovery → plan → execute → review) |
 
 ## Recommended Workflow
 
@@ -27,7 +28,7 @@ The Project Ledger (`flow/ledger.md`) is always active. It silently captures pro
 
 ## Critical Rules
 
-1. **No Auto-Chaining**: Never auto-invoke the next command. Wait for user.
+1. **No Auto-Chaining**: Never auto-invoke the next command. Wait for user. **Exception**: When autopilot mode is ON (`flow/.autopilot` exists), commands auto-chain per the autopilot flow skill.
 2. **Discovery First**: Recommend `/discovery-plan` before `/create-plan` for new features.
 3. **Tests Last**: Tests are always the last phase of any implementation plan.
 4. **Build at End Only**: Run `npm run build` only after ALL phases complete.

package/templates/shared/CLAUDE.md.template

@@ -12,6 +12,7 @@
 | `/review-code` | Review local uncommitted changes |
 | `/review-pr` | Review a Pull Request |
 | `/write-tests` | Write tests to achieve coverage target |
+| `/flow` | Toggle autopilot mode (auto-chains discovery → plan → execute → review) |
 
 ## Recommended Workflow
 
@@ -27,8 +28,8 @@ The Project Ledger (`flow/ledger.md`) is always active. It silently captures pro
 
 ## Critical Rules
 
-1. **No Auto-Chaining**: Never auto-invoke the next command. Wait for user.
-2. **Discovery First**: Recommend `/discovery-plan` before `/create-plan` for new features.
+1. **No Auto-Chaining**: Never auto-invoke the next command. Wait for user. **Exception**: When autopilot mode is ON (`flow/.autopilot` exists), commands auto-chain per `.claude/rules/core/autopilot-mode.md`.
+2. **Discovery First**: `/discovery-plan` is **required** before `/create-plan`. Plans cannot be created without a discovery document. No exceptions.
 3. **Tests Last**: Tests are always the last phase of any implementation plan.
 4. **Build at End Only**: Run `npm run build` only after ALL phases complete.