planflow-ai 1.3.5 → 1.4.3

package/.claude/resources/patterns/plans-templates.md

@@ -51,8 +51,10 @@ Use this template when creating new implementation plans:
 
 **Scope**: [What this phase covers]
 **Complexity**: X/10
+**Dependencies**: None
 
 - [ ] Task 1
+  <verify>npx tsc --noEmit src/path/to/file.ts</verify>
 - [ ] Task 2
 
 **Build Verification**: Run `npm run build`
@@ -61,6 +63,7 @@ Use this template when creating new implementation plans:
 
 **Scope**: [What this phase covers]
 **Complexity**: X/10
+**Dependencies**: Phase 1
 
 - [ ] Task 1
 - [ ] Task 2
@@ -71,6 +74,7 @@ Use this template when creating new implementation plans:
 
 **Scope**: Write comprehensive tests
 **Complexity**: X/10
+**Dependencies**: Phase 1, Phase 2, ..., Phase N-1
 
 - [ ] Unit tests for logic hooks
 - [ ] Unit tests for utilities
@@ -87,6 +91,130 @@ Use this template when creating new implementation plans:
 
 ---
 
+## Dependencies Field
+
+The optional `**Dependencies**` field declares which phases must complete before a phase can start. This enables wave-based parallel execution.
+
+### Syntax
+
+- `**Dependencies**: None` — Phase has no dependencies and can run in the first wave (parallel with other independent phases)
+- `**Dependencies**: Phase 1, Phase 3` — Phase depends on Phases 1 and 3 completing first
+- **Omitting the field entirely** — Backward-compatible default; phase depends on the immediately previous phase (sequential execution)
+
+### Rules
+
+1. The Tests phase (always last) depends on ALL prior phases — it is never parallelized
+2. Phases with `Dependencies: None` form the first execution wave
+3. A phase cannot depend on itself or on phases that come after it
+4. When in doubt, omit the field to default to sequential execution
+
+### Example
+
+```markdown
+### Phase 1: Types and Schemas
+**Scope**: Define TypeScript types
+**Complexity**: 3/10
+**Dependencies**: None
+
+### Phase 2: Config Parser
+**Scope**: Implement config parsing
+**Complexity**: 4/10
+**Dependencies**: Phase 1
+
+### Phase 3: CLI Commands
+**Scope**: Implement CLI interface
+**Complexity**: 4/10
+**Dependencies**: Phase 1
+
+### Phase 4: Integration
+**Scope**: Connect all pieces
+**Complexity**: 5/10
+**Dependencies**: Phase 2, Phase 3
+
+### Phase 5: Tests (Final)
+**Scope**: Write comprehensive tests
+**Complexity**: 5/10
+**Dependencies**: Phase 1, Phase 2, Phase 3, Phase 4
+```
+
+In this example, Phases 2 and 3 can run in parallel (both only depend on Phase 1). Phase 4 waits for both 2 and 3. Phase 5 (tests) waits for everything.
+
+---
+
+## Verify Tag
+
+The optional `<verify>` tag allows tasks to include a verification command that runs immediately after the task completes. This enables early error detection — failures are caught per-task instead of waiting until the final build step.
+
+### Syntax
+
+Add a `<verify>` tag indented under a task checkbox:
+
+```markdown
+- [ ] Create type definitions in `/src/types/workflow.ts`
+  <verify>npx tsc --noEmit src/types/workflow.ts</verify>
+```
+
+The `<verify>` tag contains a single shell command that validates the task's output. The command should be **targeted** (single file or narrow scope) rather than a full build.
+
+### Rules
+
+1. **Optional**: Tasks without a `<verify>` tag skip verification entirely (backward compatible)
+2. **One command per tag**: Each `<verify>` tag contains exactly one shell command
+3. **Targeted checks only**: Use single-file or narrow-scope commands — never full builds
+4. **Indented under the task**: The `<verify>` tag must be indented under its parent task checkbox
+5. **No verify for manual-review tasks**: Config files, documentation, and other tasks requiring human judgment should omit `<verify>`
+
+### Examples
+
+**Task with verification:**
+
+```markdown
+- [ ] Create `UserProfile` type in `/src/types/user.ts`
+  <verify>npx tsc --noEmit src/types/user.ts</verify>
+- [ ] Write unit tests for user validation
+  <verify>npx jest src/types/__tests__/user.test.ts --no-coverage</verify>
+```
+
+**Task without verification (backward compatible):**
+
+```markdown
+- [ ] Update `.flowconfig` with new setting
+- [ ] Add documentation for the new feature
+```
+
+**Mixed phase (some tasks verified, some not):**
+
+```markdown
+### Phase 2: Backend Implementation
+
+**Scope**: Implement API routes and data layer.
+**Complexity**: 6/10
+**Dependencies**: Phase 1
+
+- [ ] Create API route handler in `/src/routes/workflow.ts`
+  <verify>npx tsc --noEmit src/routes/workflow.ts</verify>
+- [ ] Add database migration for `workflow_steps` table
+- [ ] Create service layer in `/src/services/workflow.ts`
+  <verify>npx tsc --noEmit src/services/workflow.ts</verify>
+
+**Build Verification**: Run `npm run build`
+```
+
+### Heuristic Reference
+
+When writing plans, use these heuristics to decide which tasks get `<verify>` tags:
+
+| Task Type | Verify Command | Example |
+|-----------|---------------|---------|
+| File creation (`.ts`) | `npx tsc --noEmit <file>` | `npx tsc --noEmit src/types/user.ts` |
+| Test writing | `npx jest <test-file> --no-coverage` | `npx jest src/__tests__/user.test.ts --no-coverage` |
+| Schema/type definition | `npx tsc --noEmit <type-file>` | `npx tsc --noEmit src/types/schema.ts` |
+| Config file changes | No verify (manual review) | — |
+| Documentation | No verify (manual review) | — |
+| Generic/ambiguous tasks | No verify (default) | — |
+
+---
+
 ## Phase Templates
 
 ### Types and Schemas Phase
@@ -96,9 +224,12 @@ Use this template when creating new implementation plans:
 
 **Scope**: Define all TypeScript types and Zod schemas needed for the feature.
 **Complexity**: 3/10
+**Dependencies**: None
 
 - [ ] Create type definitions in `/src/types/`
+  <verify>npx tsc --noEmit src/types/feature.ts</verify>
 - [ ] Create Zod validation schemas in `/src/types/rest-inputs.ts`
+  <verify>npx tsc --noEmit src/types/rest-inputs.ts</verify>
 
 **Build Verification**: Run `npm run build`
 ```
@@ -110,9 +241,12 @@ Use this template when creating new implementation plans:
 
 **Scope**: Implement API routes and commands.
 **Complexity**: 7/10
+**Dependencies**: Phase 1
 
 - [ ] Create command in `/src/commands/`
+  <verify>npx tsc --noEmit src/commands/feature.ts</verify>
 - [ ] Create API route in `/src/app/api/`
+  <verify>npx tsc --noEmit src/app/api/feature/route.ts</verify>
 - [ ] Add database operations if needed
 
 **Build Verification**: Run `npm run build`
@@ -125,8 +259,10 @@ Use this template when creating new implementation plans:
 
 **Scope**: Implement Zustand stores for state management.
 **Complexity**: 5/10
+**Dependencies**: Phase 1
 
 - [ ] Create or extend store in `/src/stores/`
+  <verify>npx tsc --noEmit src/stores/featureStore.ts</verify>
 - [ ] Add actions and selectors
 
 **Build Verification**: Run `npm run build`
@@ -139,9 +275,12 @@ Use this template when creating new implementation plans:
 
 **Scope**: Build the user interface components.
 **Complexity**: 6/10
+**Dependencies**: Phase 3
 
 - [ ] Create logic hook (`useFeatureLogic.internal.ts`)
+  <verify>npx tsc --noEmit src/components/feature/useFeatureLogic.internal.ts</verify>
 - [ ] Create view component (`index.tsx`)
+  <verify>npx tsc --noEmit src/components/feature/index.tsx</verify>
 - [ ] Follow view/logic separation pattern
 
 **Build Verification**: Run `npm run build`
@@ -154,6 +293,7 @@ Use this template when creating new implementation plans:
 
 **Scope**: Connect all pieces and verify functionality.
 **Complexity**: 4/10
+**Dependencies**: Phase 2, Phase 4
 
 - [ ] Integrate components with pages
 - [ ] Connect to API endpoints
@@ -169,11 +309,16 @@ Use this template when creating new implementation plans:
 
 **Scope**: Write comprehensive tests for all new code.
 **Complexity**: 5/10
+**Dependencies**: Phase 1, Phase 2, Phase 3, Phase 4, Phase 5
 
 - [ ] Unit tests for logic hooks (`*.client.test.ts`)
+  <verify>npx jest src/components/feature/__tests__/useFeatureLogic.test.ts --no-coverage</verify>
 - [ ] Unit tests for utility functions
+  <verify>npx jest src/utils/__tests__/feature.test.ts --no-coverage</verify>
 - [ ] Integration tests for API routes
+  <verify>npx jest src/app/api/feature/__tests__/route.test.ts --no-coverage</verify>
 - [ ] Command tests
+  <verify>npx jest src/commands/__tests__/feature.test.ts --no-coverage</verify>
 
 **Build Verification**: Run `npm run build && npm run test`
 ```
@@ -226,4 +371,11 @@ Based on complexity scores (per `.claude/resources/core/complexity-scoring.md`):
 - **Phases 3-4**: Can be aggregated (combined complexity: 11, but cautious)
 - **Phase 5**: Can aggregate with Phase 6 if simple
 - **Phase 6**: Tests - always execute separately
+
+Based on dependency graph (when Dependencies fields are present):
+
+- **Wave 1**: Phase 1 (no dependencies)
+- **Wave 2**: Phases 2, 3 (both depend only on Phase 1 — run in parallel)
+- **Wave 3**: Phases 4, 5 (depend on earlier waves)
+- **Wave 4**: Phase 6 (Tests — always sequential, always last)
 ```

package/.claude/resources/skills/create-plan-skill.md

@@ -21,7 +21,9 @@ This skill is **strictly for creating plan documents**. The process:
 1. **Reads** the discovery document or gathers requirements
 2. **Analyzes** complexity and scope
 3. **Structures** phases with complexity scores
-4. **Generates** a plan markdown file
+4. **Analyzes** phase independence for parallel execution
+5. **Generates** verify sections for applicable tasks
+6. **Generates** a plan markdown file
 
 **No code, no implementation, no source file modifications.**
 
@@ -96,8 +98,10 @@ Create phases following these guidelines:
 
 **Scope**: [What this phase covers]
 **Complexity**: X/10
+**Dependencies**: [None | Phase N, Phase M | omit for sequential default]
 
 - [ ] Task 1
+  <verify>npx tsc --noEmit src/path/to/file.ts</verify>
 - [ ] Task 2
 
 **Build Verification**: Run `npm run build`
@@ -122,9 +126,64 @@ Create phases following these guidelines:
 | 7-8   | High      | Complex, multiple considerations |
 | 9-10  | Very High | Significant complexity/risk      |
 
+#### Auto-Generating Verify Sections
+
+When creating tasks within phases, auto-generate `<verify>` tags based on the task type using these heuristics:
+
+| Task Type | Verify Command | When to Apply |
+|-----------|---------------|---------------|
+| File creation (`.ts`, `.tsx`) | `npx tsc --noEmit <file>` | Task creates or modifies a TypeScript source file |
+| Test writing | `npx jest <test-file> --no-coverage` | Task creates or modifies a test file |
+| Schema/type definition | `npx tsc --noEmit <type-file>` | Task creates or modifies type definitions or schemas |
+| Config file changes | No verify | Task modifies `.flowconfig`, `tsconfig.json`, or similar config files |
+| Documentation/markdown | No verify | Task creates or updates `.md` files |
+| Generic/ambiguous tasks | No verify | Task description does not clearly indicate a verifiable output file |
+
+**Rules for auto-generation:**
+
+1. Only generate `<verify>` when the task clearly references a specific file path
+2. Use the file path from the task description in the verify command
+3. Prefer `npx tsc --noEmit` for source files and `npx jest --no-coverage` for test files
+4. When in doubt, omit the `<verify>` tag — false verification commands are worse than no verification
+5. Never generate full-build commands (`npm run build`) as verify tags — those belong in Build Verification
+
+---
+
+### Step 4: Analyze Phase Dependencies
+
+After structuring phases, analyze which phases are independent and can run in parallel:
+
+1. **For each phase**, determine its data and code dependencies on other phases:
+   - Does this phase use types/interfaces defined in another phase?
+   - Does this phase call functions or APIs created in another phase?
+   - Does this phase modify files that another phase also modifies?
+
+2. **Mark independent phases** with `**Dependencies**: None` when they:
+   - Only depend on pre-existing code (not created in this plan)
+   - Have no shared file modifications with other phases in the same wave
+   - Can be implemented and verified independently
+
+3. **Mark dependent phases** with explicit dependency lists:
+   - `**Dependencies**: Phase 1` — depends on one phase
+   - `**Dependencies**: Phase 1, Phase 3` — depends on multiple phases
+   - List only **direct** dependencies (not transitive ones)
+
+4. **Default to sequential** (omit the field) when:
+   - Unsure whether phases are truly independent
+   - Phases touch overlapping files
+   - The dependency relationship is ambiguous
+
+5. **Tests phase**: Always list ALL prior phases as dependencies. The Tests phase is never parallelized.
+
+**Common independence patterns**:
+- Types/schemas phase is often `Dependencies: None` (foundational, no prior phases needed)
+- Backend API and CLI commands may be independent if they don't share code
+- Store and UI phases often depend on types but may be independent of each other
+- Integration phases typically depend on multiple prior phases
+
 ---
 
-### Step 4: Add Key Changes Summary
+### Step 5: Add Key Changes Summary
 
 Document the most important modifications:
 
@@ -137,7 +196,7 @@ Document the most important modifications:
 
 ---
 
-### Step 5: Generate Plan Document
+### Step 6: Generate Plan Document
 
 Create the plan markdown file:
 
@@ -152,7 +211,7 @@ Create the plan markdown file:
 3. Non-Goals
 4. Requirements Summary (FR, NFR, Constraints)
 5. Risks
-6. Phases (with complexity scores)
+6. Phases (with complexity scores and optional dependency declarations)
 7. Key Changes
 
 ---
@@ -217,8 +276,10 @@ The plan document should follow the template in `.claude/resources/patterns/plan
 
 **Scope**: [What this phase covers]
 **Complexity**: X/10
+**Dependencies**: None
 
 - [ ] Task 1
+  <verify>npx tsc --noEmit src/path/to/file.ts</verify>
 - [ ] Task 2
 
 **Build Verification**: Run `npm run build`
@@ -227,8 +288,10 @@ The plan document should follow the template in `.claude/resources/patterns/plan
 
 **Scope**: Write comprehensive tests
 **Complexity**: X/10
+**Dependencies**: Phase 1, Phase 2, ..., Phase N-1
 
 - [ ] Unit tests
+  <verify>npx jest src/path/to/test.ts --no-coverage</verify>
 - [ ] Integration tests
 
 **Build Verification**: Run `npm run build && npm run test`
@@ -247,9 +310,12 @@ Before completing the plan, verify:
 - [ ] Plan is saved in `flow/plans/` folder
 - [ ] File uses snake_case naming: `plan_<feature>_v<version>.md`
 - [ ] All phases have complexity scores (X/10)
-- [ ] Tests are the LAST phase
+- [ ] Phase dependencies are analyzed and declared where appropriate
+- [ ] Tests are the LAST phase with dependencies on ALL prior phases
 - [ ] Key Changes section is populated
 - [ ] Discovery document is referenced (discovery is required, never skipped)
+- [ ] Verify sections are generated for applicable tasks (file creation, test writing, schema/type tasks)
+- [ ] Verify sections are omitted for config, documentation, and generic tasks
 - [ ] **NO implementation code is included**
 - [ ] **NO source files were created or modified**