planflow-ai 1.0.0 → 1.0.2

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

@@ -46,7 +46,7 @@ WORKFLOW:
   3. Generates contract document with endpoints, schemas, and integration notes
 
 RECOMMENDED MODEL:
-  Claude Opus 4.5 or Sonnet 4.5 for best results
+  Claude Opus 4.6 or Sonnet 4.5 for best results
 
 RELATED COMMANDS:
   /discovery-plan    Create discovery document from contract

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

@@ -49,7 +49,7 @@ WORKFLOW:
   5. Tests phase is always last
 
 RECOMMENDED MODEL:
-  Claude Opus 4.5 or Sonnet 4.5 for best results
+  Claude Opus 4.6 or Sonnet 4.5 for best results
 
 RELATED COMMANDS:
   /discovery-plan    Run discovery first (recommended)

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

@@ -12,6 +12,18 @@ This command creates a discovery document for gathering and clarifying requireme
 
 ---
 
+> ⚠️ **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
+>
+> After creating the discovery document, the command STOPS and waits for user review.
+
+---
+
 
 ## Help
 
@@ -43,14 +55,16 @@ OUTPUT:
 
 WORKFLOW:
   1. Reads all referenced documents
-  2. Asks clarifying questions (via Plan mode Questions UI)
-  3. Documents requirements (FR, NFR, Constraints)
-  4. Proposes high-level approach (no code)
-  5. Creates discovery document for review
-  6. User reviews and refines before /create-plan
+  2. Finds all related code references in codebase
+  3. Asks clarifying questions (via Plan mode Questions UI)
+  4. Documents requirements (FR, NFR, Constraints)
+  5. Proposes high-level approach (no code)
+  6. Creates discovery document for review
+  7. Asks user if they want to proceed to /create-plan
+  8. Waits for user confirmation before proceeding
 
 RECOMMENDED MODEL:
-  Claude Opus 4.5 or Sonnet 4.5 for best results
+  Claude Opus 4.6 or Sonnet 4.5 for best results
 
 RELATED COMMANDS:
   /create-contract   Create contract from API docs first
@@ -71,8 +85,10 @@ 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  |
-| **No Auto-Chaining**     | NEVER auto-invoke /create-plan - user must invoke it     |
-| **Complete and Stop**    | After presenting results, STOP and wait for user         |
+| **Ask Before Proceeding**| ASK user if they want to proceed to /create-plan         |
+| **No Auto-Execution**    | Do NOT auto-invoke commands without user confirmation    |
+| **NO PLANNING**          | Do NOT create implementation plans during discovery      |
+| **NO EXECUTION**         | Do NOT execute any implementation steps                  |
 
 ---
 
@@ -125,13 +141,16 @@ Check `flow/discovery/` for existing discovery documents for this feature:
 The skill will:
 
 1. Read all referenced documents
-2. Ask clarifying questions via Interactive Questions Tool
-3. Track question status
-4. Document requirements (FR, NFR, Constraints)
-5. Identify technical considerations
-6. Propose high-level approach
-7. Document risks and unknowns
-8. Generate discovery document
+2. Find all related code references in the codebase
+3. Ask clarifying questions via Interactive Questions Tool
+4. Track question status
+5. Document requirements (FR, NFR, Constraints)
+6. Identify technical considerations
+7. Propose high-level approach
+8. Document risks and unknowns
+9. Generate discovery document
+10. Ask user if they want to proceed to /create-plan
+11. Wait for user confirmation before proceeding
 
 See: `.claude/rules/skills/discovery-skill.md`
 
@@ -152,13 +171,25 @@ Discovery Complete!
 
 **Deliverable Created**: `flow/discovery/discovery_<feature>_v1.md`
 
-**Next Steps** (user must invoke manually):
+**Next Steps**:
 1. Review the discovery document above
-2. Request any refinements or additions
-3. When ready, invoke `/create-plan @flow/discovery/discovery_<feature>_v1.md`
+2. Request any refinements or additions (if needed)
+3. Proceed to planning when ready
 ```
 
-**CRITICAL**: This command is now complete. Do NOT auto-invoke `/create-plan`. Wait for the user to explicitly invoke it.
+**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
+```
+
+⚠️ **WAIT for user response before proceeding**
+
+Do NOT auto-invoke `/create-plan` without user confirmation.
 
 ---
 
@@ -303,10 +334,14 @@ This skill is **strictly for gathering and documenting requirements**. The proce
 | -------------------------------------- | ----------------------------------------- |
 | Create/edit source code files          | Discovery is requirements gathering only  |
 | Write implementation code in responses | No code during discovery                  |
-| Create implementation plans            | Plans come after discovery                |
+| Create implementation plans            | Plans come after discovery via /create-plan |
+| Create files in `flow/plans/`          | Planning is a separate command            |
+| Auto-invoke /create-plan without asking| Must ASK user before proceeding           |
+| Execute implementation steps           | Discovery does not execute anything       |
 | Modify configuration files             | No codebase changes                       |
 | Run build or test commands             | No execution commands                     |
 | Create files outside `flow/discovery/` | Only write discovery documents            |
+| Proceed without user confirmation      | Must wait for user response               |
 
 ### Allowed Actions
 
@@ -366,7 +401,79 @@ This skill is **strictly for gathering and documenting requirements**. The proce
 
 ---
 
-### Step 2: Ask Clarifying Questions
+### Step 2: Find All Related Code References
+
+**BEFORE asking questions**, search the codebase to find **all code locations** related to the feature.
+
+**Why**: Understanding where a feature is currently used prevents incomplete implementations and reveals hidden dependencies.
+
+**Actions**:
+
+1. **Identify key terms** from the user's request (e.g., "user profile", "workflow editor")
+2. **Search for components** using Grep:
+   ```bash
+   Grep: "UserProfile|userProfile|user-profile"
+         --output_mode content --type ts --type tsx
+   ```
+3. **Search for types** using Grep:
+   ```bash
+   Grep: "interface.*User|type.*User"
+         --output_mode content --type ts
+   ```
+4. **Search for API routes** using Glob:
+   ```bash
+   Glob: "**/api/**/user*/**"
+   Glob: "**/api/**/profile*/**"
+   ```
+5. **Search for stores** using Grep:
+   ```bash
+   Grep: "userStore|profileStore|useUser"
+         --output_mode content --type ts
+   ```
+6. **Search for tests** using Glob:
+   ```bash
+   Glob: "**/*user*.test.ts*"
+   Glob: "**/*profile*.test.ts*"
+   ```
+
+**Document Format**:
+
+```markdown
+## Code Context Analysis
+
+### Components Found
+| File | Usage | Line(s) |
+|------|-------|---------|
+| `src/components/UserProfile.tsx` | Main profile component | - |
+| `src/components/Settings/ProfileSettings.tsx` | Settings integration | - |
+
+### API Endpoints Found
+| File | Endpoint | Method |
+|------|----------|--------|
+| `src/app/api/user/profile/route.ts` | `/api/user/profile` | GET, PUT |
+
+### State Management Found
+| File | Purpose |
+|------|---------|
+| `src/stores/userStore.ts` | User profile state |
+
+### Type Definitions Found
+| File | Types |
+|------|-------|
+| `src/types/user.ts` | `User`, `UserProfile` |
+
+**Total References**: X files across Y categories
+
+### Key Patterns Observed
+- [Pattern 1 from existing code]
+- [Pattern 2 from existing code]
+```
+
+**Read Key Files**: After finding references, read 2-3 key files to understand current implementation patterns.
+
+---
+
+### Step 3: Ask Clarifying Questions
 
 Ask questions about gaps identified in documents and unclear requirements.
 
@@ -396,7 +503,7 @@ Follow `.claude/rules/tools/interactive-questions-tool.md`:
 
 ---
 
-### Step 3: Track Question Status
+### Step 4: Track Question Status
 
 Maintain a question tracking table:
 
@@ -419,7 +526,7 @@ Maintain a question tracking table:
 
 ---
 
-### Step 4: Document Requirements
+### Step 5: Document Requirements
 
 Categorize requirements as they are gathered:
 
@@ -438,7 +545,7 @@ Categorize requirements as they are gathered:
 
 ---
 
-### Step 5: Identify Technical Considerations
+### Step 6: Identify Technical Considerations
 
 Document high-level technical insights (NO implementation code):
 
@@ -460,7 +567,7 @@ Document high-level technical insights (NO implementation code):
 
 ---
 
-### Step 6: Propose High-Level Approach
+### Step 7: Propose High-Level Approach
 
 Suggest an approach based on findings (NO implementation code):
 
@@ -481,7 +588,7 @@ Based on the requirements gathered, I recommend:
 
 ---
 
-### Step 7: Document Risks and Unknowns
+### Step 8: Document Risks and Unknowns
 
 Capture risks discovered:
 
@@ -500,7 +607,7 @@ Capture risks discovered:
 
 ---
 
-### Step 8: Generate Discovery Document
+### Step 9: Generate Discovery Document
 
 Create the discovery markdown file:
 
@@ -512,12 +619,13 @@ Create the discovery markdown file:
 
 1. Context
 2. Referenced Documents
-3. Requirements Gathered (FR, NFR, Constraints)
-4. Open Questions (all answered)
-5. Technical Considerations
-6. Proposed Approach
-7. Risks and Unknowns
-8. Next Steps
+3. Code Context Analysis
+4. Requirements Gathered (FR, NFR, Constraints)
+5. Open Questions (all answered)
+6. Technical Considerations
+7. Proposed Approach
+8. Risks and Unknowns
+9. Next Steps
 
 ---
 
@@ -538,6 +646,8 @@ The discovery document should follow the template in `.claude/rules/patterns/dis
 Before completing discovery, verify:
 
 - [ ] All referenced documents have been read
+- [ ] Code context analysis completed (all related files found)
+- [ ] Key patterns observed and documented
 - [ ] Document is saved in `flow/discovery/` folder
 - [ ] File uses correct naming convention
 - [ ] Open questions table has no "Blocked" status
@@ -548,6 +658,11 @@ Before completing discovery, verify:
 - [ ] Next steps are defined (pointing to `/create-plan`)
 - [ ] **NO implementation code is included**
 - [ ] **NO source files were created or modified**
+- [ ] **NO implementation plans were created**
+- [ ] **NO files created in flow/plans/ directory**
+- [ ] **ASKED user if they want to proceed to /create-plan**
+- [ ] **WAITING for user confirmation before proceeding**
+- [ ] **Did NOT auto-invoke /create-plan without asking**
 
 ---
 

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

@@ -64,7 +64,7 @@ SAFETY:
   - Prevents accidental data loss
 
 RECOMMENDED MODEL:
-  Claude Opus 4.5 or Sonnet 4.5 for best results
+  Claude Opus 4.6 or Sonnet 4.5 for best results
 
 RELATED COMMANDS:
   /create-plan       Create a plan first

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

@@ -54,7 +54,7 @@ REVIEW CATEGORIES:
   - Security considerations
 
 RECOMMENDED MODEL:
-  Claude Opus 4.5 or Sonnet 4.5 for best results
+  Claude Opus 4.6 or Sonnet 4.5 for best results
 
 RELATED COMMANDS:
   /review-pr    Review a Pull Request instead

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

@@ -57,7 +57,7 @@ REVIEW INCLUDES:
   - Approval recommendation
 
 RECOMMENDED MODEL:
-  Claude Opus 4.5 or Sonnet 4.5 for best results
+  Claude Opus 4.6 or Sonnet 4.5 for best results
 
 RELATED COMMANDS:
   /review-code   Review local changes instead

package/.claude/commands/setup.md

@@ -74,7 +74,7 @@ DETECTS:
   Libraries:    Zod, Prisma, Zustand, Redux, TailwindCSS, React Query, and 50+
 
 RECOMMENDED MODEL:
-  Claude Opus 4.5 or Sonnet 4.5 for best results
+  Claude Opus 4.6 or Sonnet 4.5 for best results
 
 RELATED COMMANDS:
   /discovery-plan    Start discovery after setup

package/.claude/commands/write-tests.md

@@ -61,7 +61,7 @@ SUPPORTED FRAMEWORKS:
   - Pytest (Python)
 
 RECOMMENDED MODEL:
-  Claude Opus 4.5 or Sonnet 4.5 for best results
+  Claude Opus 4.6 or Sonnet 4.5 for best results
 
 RELATED COMMANDS:
   /execute-plan   Tests are the last phase of plan execution

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

@@ -4,10 +4,11 @@
 Discovery is a **pre-planning phase** where we:
 
 1. **Gather Information**: Read referenced files, contracts, and documentation
-2. **Ask Questions**: Clarify every unclear aspect with the user
-3. **Explore Unknowns**: Investigate technical feasibility and constraints
-4. **Document Findings**: Create a comprehensive discovery document
-5. **Prepare for Planning**: Provide all context needed to create an implementation plan
+2. **Find Code Context**: Search codebase for all related implementations and dependencies
+3. **Ask Questions**: Clarify every unclear aspect with the user
+4. **Explore Unknowns**: Investigate technical feasibility and constraints
+5. **Document Findings**: Create a comprehensive discovery document
+6. **Prepare for Planning**: Provide all context needed to create an implementation plan
 
 **Workflow**: Discovery Output → Implementation Plan → Execution
 
@@ -113,7 +114,96 @@ Categorize all gathered requirements:
 
 ---
 
-### 2. Ask Questions Using Interactive Questions Tool
+### 2. Find All Related Code References
+
+**Before proceeding with discovery**, search the codebase to find **all code locations** related to the feature being discovered.
+
+**Why**: Understanding where a feature is currently used prevents incomplete implementations and reveals hidden dependencies.
+
+**Process**:
+
+1. **Identify key terms** from the user's request (e.g., "user profile", "workflow editor", "authentication")
+2. **Search for code references** using Grep:
+   - Component names
+   - Function names
+   - Type definitions
+   - API endpoints
+   - Database models
+   - Store actions/selectors
+3. **Search for file patterns** using Glob:
+   - Related component directories
+   - Test files for the feature
+   - API route files
+4. **Document all findings** in the "Code Context Analysis" section of the discovery document
+5. **Read key files** to understand current implementation patterns
+
+**Example Search Strategy**:
+
+For a request like "edit user profile":
+
+```bash
+# Search for components/functions
+Grep: "UserProfile|userProfile|user-profile"
+      --output_mode content --type ts --type tsx
+
+# Search for types
+Grep: "interface.*User|type.*User"
+      --output_mode content --type ts
+
+# Search for API routes
+Glob: "**/api/**/user*/**" or "**/api/**/profile*/**"
+
+# Search for stores
+Grep: "userStore|profileStore|useUser"
+      --output_mode content --type ts
+
+# Search for tests
+Glob: "**/*user*.test.ts*" or "**/*profile*.test.ts*"
+```
+
+**Document Format in Discovery**:
+
+```markdown
+## Code Context Analysis
+
+### Components Found
+| File | Usage | Line(s) |
+|------|-------|---------|
+| `src/components/UserProfile.tsx` | Main profile component | - |
+| `src/components/Settings/ProfileSettings.tsx` | Settings page usage | - |
+| `src/components/Dashboard/UserCard.tsx` | Dashboard card | - |
+
+### API Endpoints Found
+| File | Endpoint | Method |
+|------|----------|--------|
+| `src/app/api/user/profile/route.ts` | `/api/user/profile` | GET, PUT |
+| `src/app/api/user/avatar/route.ts` | `/api/user/avatar` | POST |
+
+### State Management Found
+| File | Purpose |
+|------|---------|
+| `src/stores/userStore.ts` | User profile state |
+| `src/stores/authStore.ts` | Authentication state (includes profile data) |
+
+### Type Definitions Found
+| File | Types |
+|------|-------|
+| `src/types/user.ts` | `User`, `UserProfile`, `UpdateProfileInput` |
+
+### Total References: 12 files across 5 categories
+```
+
+**Benefits**:
+
+- **Complete Context**: Know all places where changes will have impact
+- **Prevent Breaking Changes**: Identify all consumers before making modifications
+- **Better Estimates**: Understand full scope for complexity scoring
+- **Pattern Discovery**: Learn existing patterns from actual usage
+- **Test Coverage**: Find existing tests that need updates
+
+---
+
+### 3. Ask Questions Using Interactive Questions Tool
 
 **Use Plan mode's Questions UI** for a better user experience.
 
@@ -135,7 +225,7 @@ See `.claude/rules/tools/interactive-questions-tool.md` for detailed instruction
 
 ---
 
-### 3. Structure Discovery Documents Consistently
+### 4. Structure Discovery Documents Consistently
 
 Every discovery document must include these sections:
 
@@ -154,7 +244,7 @@ See `.claude/rules/patterns/discovery-templates.md` for the full template.
 
 ---
 
-### 4. Mark Assumptions Explicitly
+### 5. Mark Assumptions Explicitly
 
 When making assumptions, always mark them clearly:
 
@@ -171,7 +261,7 @@ When making assumptions, always mark them clearly:
 
 ---
 
-### 5. Keep Discovery High-Level
+### 6. Keep Discovery High-Level
 
 Focus on "what" not "how". Discovery captures:
 
@@ -184,7 +274,7 @@ Implementation details belong in the plan, not discovery.
 
 ---
 
-### 6. Link Discovery to Plan
+### 7. Link Discovery to Plan
 
 When discovery is complete:
 
@@ -333,6 +423,7 @@ The discovery document is the **ONLY** deliverable. It must be:
 | Pattern                        | Description                                    |
 | ------------------------------ | ---------------------------------------------- |
 | Read documents first           | Always review referenced files before asking   |
+| Find all code references       | Search codebase for all related implementations|
 | Use interactive questions      | Plan mode Questions UI for better UX           |
 | Structure consistently         | Follow the standard discovery template         |
 | Mark assumptions               | Always label and validate assumptions          |

package/.claude/rules/patterns/discovery-templates.md

@@ -19,6 +19,47 @@ Use this template when creating discovery documents:
 | `flow/references/api-contracts.md` | [Summary of relevant content] |
 | `flow/references/sse-events.md`    | [Summary of relevant content] |
 
+## Code Context Analysis
+
+[Analysis of all code locations related to this feature]
+
+### Components Found
+
+| File | Usage | Line(s) |
+|------|-------|---------|
+| `[file_path]` | [How it's used] | [line references] |
+
+### API Endpoints Found
+
+| File | Endpoint | Method |
+|------|----------|--------|
+| `[file_path]` | `[endpoint]` | [GET/POST/PUT/DELETE] |
+
+### State Management Found
+
+| File | Purpose |
+|------|---------|
+| `[file_path]` | [Store/state description] |
+
+### Type Definitions Found
+
+| File | Types |
+|------|-------|
+| `[file_path]` | [Type names] |
+
+### Other Related Files
+
+| File | Purpose |
+|------|---------|
+| `[file_path]` | [Description] |
+
+**Total References**: [count] files across [count] categories
+
+### Key Patterns Observed
+
+- [Pattern 1 observed in existing code]
+- [Pattern 2 observed in existing code]
+
 ## Requirements Gathered
 
 ### Functional Requirements
@@ -297,6 +338,65 @@ I've reviewed the following documents:
 
 ---
 
+## Code Context Analysis Example
+
+```markdown
+## Code Context Analysis
+
+I performed a comprehensive search for all code related to "user profile" functionality:
+
+### Components Found
+
+| File | Usage | Line(s) |
+|------|-------|---------|
+| `src/components/UserProfile/index.tsx` | Main profile display component | - |
+| `src/components/UserProfile/EditForm.tsx` | Profile editing form | - |
+| `src/components/Settings/ProfileSettings.tsx` | Settings page integration | - |
+| `src/components/Dashboard/UserCard.tsx` | Dashboard summary card | 45-78 |
+| `src/components/Navigation/UserMenu.tsx` | Navigation menu with profile link | 23-35 |
+
+### API Endpoints Found
+
+| File | Endpoint | Method |
+|------|----------|--------|
+| `src/app/api/user/profile/route.ts` | `/api/user/profile` | GET, PUT |
+| `src/app/api/user/avatar/route.ts` | `/api/user/avatar` | POST |
+| `src/app/api/user/settings/route.ts` | `/api/user/settings` | GET, PATCH |
+
+### State Management Found
+
+| File | Purpose |
+|------|---------|
+| `src/stores/userStore.ts` | User profile state with actions |
+| `src/stores/authStore.ts` | Includes user profile data from auth |
+
+### Type Definitions Found
+
+| File | Types |
+|------|-------|
+| `src/types/user.ts` | `User`, `UserProfile`, `UpdateProfileInput` |
+| `src/types/rest-inputs.ts` | `UpdateProfileRequestSchema` (Zod) |
+
+### Other Related Files
+
+| File | Purpose |
+|------|---------|
+| `src/utils/userValidation.ts` | Profile data validation utilities |
+| `src/hooks/useUserProfile.ts` | Custom hook for profile management |
+
+**Total References**: 12 files across 5 categories
+
+### Key Patterns Observed
+
+- **View/Logic Separation**: Components use separate logic hooks (e.g., `useUserProfileLogic.internal.ts`)
+- **Zod Validation**: All API inputs validated with Zod schemas in `types/rest-inputs.ts`
+- **State Management**: Using Zustand stores with immer for immutable updates
+- **Error Handling**: Consistent use of custom error types (`BadRequestError`, `UnauthorizedError`)
+- **Testing**: Each component has co-located `*.client.test.ts` file
+```
+
+---
+
 ## Proposed Approach Example
 
 ```markdown

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "planflow-ai",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Structured AI-assisted development workflows for discovery, planning, execution, code reviews, and testing",
   "type": "module",
   "main": "dist/cli/index.js",
   "bin": {
-    "plan-flow": "./dist/cli/index.js"
+    "planflow-ai": "./dist/cli/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brunoscardoso/plan-flow.git"
+  },
+  "homepage": "https://github.com/brunoscardoso/plan-flow#readme",
+  "bugs": {
+    "url": "https://github.com/brunoscardoso/plan-flow/issues"
   },
   "scripts": {
     "build": "tsc",
@@ -43,7 +51,7 @@
     "workflow",
     "ai-assisted"
   ],
-  "author": "",
+  "author": "Bruno Cardoso",
   "license": "MIT",
   "dependencies": {
     "commander": "^14.0.3"