planflow-ai 1.0.0

package/rules/core/complexity-scoring.mdc

@@ -0,0 +1,235 @@
+---
+description: "Core pattern for calculating task complexity scores for implementation planning and code review"
+alwaysApply: false
+---
+
+# Complexity Scoring
+
+This document defines the scoring system for plan phases. These scores determine execution strategy and help estimate implementation effort.
+
+---
+
+## Complexity Scale
+
+| Score | Level     | Description                                | Examples                                                               |
+| ----- | --------- | ------------------------------------------ | ---------------------------------------------------------------------- |
+| 0-2   | Trivial   | Simple, mechanical changes                 | Adding a type alias, renaming a variable, adding an import             |
+| 3-4   | Low       | Straightforward implementation             | Creating a simple Zod schema, adding a basic utility function          |
+| 5-6   | Medium    | Moderate complexity, some decisions        | Creating a new component with logic hook, adding a store action        |
+| 7-8   | High      | Complex implementation, multiple concerns  | API route with command pattern, complex state management               |
+| 9-10  | Very High | Highly complex, requires careful attention | Streaming implementation, complex algorithms, multi-system integration |
+
+---
+
+## Scoring Criteria
+
+Use these modifiers to calculate the complexity score for each phase:
+
+### Positive Modifiers (Add Points)
+
+| Modifier                             | Points |
+| ------------------------------------ | ------ |
+| Each new file to create              | +1     |
+| External API integration             | +1     |
+| Database operations                  | +1     |
+| Complex state management             | +1     |
+| View/logic separation pattern        | +1     |
+| Streaming or real-time features      | +2     |
+| Complex business logic or algorithms | +2     |
+| Multi-system integration             | +2     |
+| Authentication/authorization logic   | +1     |
+| Error handling with recovery         | +1     |
+
+### Negative Modifiers (Subtract Points)
+
+| Modifier                             | Points |
+| ------------------------------------ | ------ |
+| Purely mechanical/repetitive tasks   | -1     |
+| Small modifications to existing code | -1     |
+| Following existing patterns exactly  | -1     |
+| Copy/paste with minor changes        | -1     |
+
+---
+
+## Execution Strategy Based on Scores
+
+| Total Adjacent Score | Execution Strategy                                                 |
+| -------------------- | ------------------------------------------------------------------ |
+| ≤ 6                  | **Aggregate**: Execute multiple phases together in one pass        |
+| 7-10                 | **Cautious**: Execute 1-2 phases, then verify                      |
+| > 10                 | **Sequential**: Execute one phase at a time with full verification |
+
+---
+
+## Aggregation Rules
+
+1. **Can aggregate** phases when their combined complexity ≤ 6
+2. **Never aggregate** across a phase with complexity ≥ 8
+3. **Always execute separately**: Tests phase (regardless of score)
+4. **Prefer aggregation** for trivial consecutive phases (0-2 each)
+
+---
+
+## Examples
+
+### Example 1: Aggregatable Phases (Combined ≤ 6)
+
+```markdown
+### Phase 1: Types and Schemas
+
+**Complexity**: 3/10
+
+- [ ] Create WorkflowStep type
+- [ ] Create Zod schema
+
+### Phase 2: Utility Functions
+
+**Complexity**: 2/10
+
+- [ ] Create transformation helper
+
+<!-- Combined complexity: 5 → Execute together -->
+```
+
+### Example 2: Must Execute Separately (Phase ≥ 8)
+
+```markdown
+### Phase 3: API Route with Streaming
+
+**Complexity**: 9/10
+
+- [ ] Create streaming endpoint
+- [ ] Handle SSE events
+- [ ] Implement error recovery
+
+### Phase 4: UI Components
+
+**Complexity**: 6/10
+
+- [ ] Create component with view/logic separation
+- [ ] Integrate with store
+
+<!-- Phase 3 is ≥ 8, execute separately. Phase 4 starts fresh. -->
+```
+
+### Example 3: Sequential Execution (Total > 10)
+
+```markdown
+### Phase 1: Database Schema
+
+**Complexity**: 5/10
+
+### Phase 2: Backend API
+
+**Complexity**: 7/10
+
+### Phase 3: Frontend Components
+
+**Complexity**: 6/10
+
+<!-- Adjacent totals exceed 10, execute one at a time -->
+```
+
+---
+
+## Phase Format with Complexity
+
+Every phase in a plan must include a complexity score:
+
+```markdown
+### Phase 1: [Phase Name]
+
+**Scope**: [What this phase covers]
+**Complexity**: X/10
+
+- [ ] Task 1
+- [ ] Task 2
+
+**Build Verification**: Run `npm run build`
+```
+
+---
+
+## Scoring Guidelines
+
+### When in Doubt, Score Higher
+
+If uncertain about complexity, err on the side of a higher score. It's better to execute cautiously than to rush through a complex phase.
+
+### Re-evaluate During Execution
+
+If a phase turns out to be more complex than estimated:
+
+1. Stop execution
+2. Update the complexity score in the plan
+3. Adjust execution strategy accordingly
+
+### Common Complexity Patterns
+
+| Task Type                       | Typical Score |
+| ------------------------------- | ------------- |
+| Type definitions only           | 2-3           |
+| Simple utility function         | 2-3           |
+| Zod schema creation             | 3-4           |
+| Basic React component           | 4-5           |
+| Component with view/logic split | 5-6           |
+| Zustand store actions           | 4-5           |
+| REST API route                  | 5-6           |
+| API route with command pattern  | 6-7           |
+| Database operations             | 5-7           |
+| Streaming/SSE implementation    | 8-9           |
+| Complex algorithm               | 7-9           |
+| Multi-service integration       | 8-10          |
+| Unit tests                      | 3-5           |
+| Integration tests               | 5-6           |
+
+---
+
+## Real-World Scoring Examples
+
+### Example A: Add a New Form Field
+
+**Scenario**: Add an email field to the user registration form.
+
+| Modifier | Points | Reason |
+|----------|--------|--------|
+| Modify existing component | -1 | Small modification |
+| Following existing patterns | -1 | Other fields already exist |
+| Add Zod validation | +1 | Schema update |
+| **Total** | **2/10** | Trivial |
+
+**Execution**: Can be aggregated with other trivial phases.
+
+---
+
+### Example B: Create User Dashboard API
+
+**Scenario**: Create an API endpoint that fetches user data with analytics.
+
+| Modifier | Points | Reason |
+|----------|--------|--------|
+| New file (route.ts) | +1 | Creating API route |
+| Database operations | +1 | Fetch user data |
+| External API integration | +1 | Analytics service |
+| Error handling with recovery | +1 | Handle service failures |
+| Complex business logic | +2 | Aggregate multiple data sources |
+| **Total** | **6/10** | Medium |
+
+**Execution**: Can be aggregated if adjacent phase is ≤ 0.
+
+---
+
+### Example C: Implement Real-time Chat Feature
+
+**Scenario**: Add WebSocket-based chat with message persistence.
+
+| Modifier | Points | Reason |
+|----------|--------|--------|
+| New files (3 files) | +3 | Route, hook, component |
+| Streaming/real-time | +2 | WebSocket handling |
+| Database operations | +1 | Message persistence |
+| Complex state management | +1 | Chat state with optimistic updates |
+| Multi-system integration | +2 | WebSocket + DB + Auth |
+| **Total** | **9/10** | Very High |
+
+**Execution**: Must execute separately. Never aggregate with other phases.

package/rules/core/forbidden-patterns.mdc

@@ -0,0 +1,263 @@
+---
+description: "Anti-patterns and practices to avoid in all code"
+alwaysApply: true
+---
+
+# Forbidden Patterns
+
+This file defines **anti-patterns and practices to avoid** in your project. Add patterns that your team has identified as problematic and wants the AI to avoid during code generation.
+
+---
+
+## How to Use This File
+
+1. **Add anti-patterns** that cause problems in your codebase
+2. **Show examples** of the problematic code
+3. **Explain why** each pattern is harmful
+4. **Reference the fix** in `.cursor/rules/core/allowed-patterns.mdc` when applicable
+
+---
+
+## Example Pattern Structure
+
+### DON'T: Pattern Name
+
+**Problem**: Brief description of why this is problematic.
+
+```typescript
+// BAD - Example of the anti-pattern
+const badExample = doThingWrong()
+```
+
+**Why This is Wrong**:
+
+- Reason 1
+- Reason 2
+
+**Fix**: Description of the correct approach or link to `.cursor/rules/core/allowed-patterns.mdc`.
+
+---
+
+## Example Anti-Patterns
+
+### 1. DON'T Use Magic Numbers
+
+**Problem**: Hardcoded numbers without context make code hard to understand and maintain.
+
+```typescript
+// BAD - What does 86400000 mean?
+setTimeout(cleanup, 86400000)
+
+// BAD - Why 5? What if it needs to change?
+if (retryCount > 5) {
+  throw new Error('Too many retries')
+}
+```
+
+**Why This is Wrong**:
+
+- No context for what the number represents
+- Hard to find and update when requirements change
+- Easy to introduce bugs with typos
+
+**Fix**: Use named constants with descriptive names.
+
+```typescript
+// GOOD
+const ONE_DAY_MS = 24 * 60 * 60 * 1000
+setTimeout(cleanup, ONE_DAY_MS)
+
+const MAX_RETRY_ATTEMPTS = 5
+if (retryCount > MAX_RETRY_ATTEMPTS) {
+  throw new Error('Too many retries')
+}
+```
+
+---
+
+### 2. DON'T Swallow Errors Silently
+
+**Problem**: Catching errors without handling them hides bugs and makes debugging impossible.
+
+```typescript
+// BAD - Error is completely ignored
+try {
+  await saveData(data)
+} catch (error) {
+  // Silent failure - no one knows something went wrong
+}
+
+// BAD - Generic catch that hides the real issue
+try {
+  await complexOperation()
+} catch {
+  return null
+}
+```
+
+**Why This is Wrong**:
+
+- Bugs go unnoticed until they cause bigger problems
+- Impossible to debug issues in production
+- Users don't know their action failed
+
+**Fix**: Always log errors and provide appropriate user feedback.
+
+```typescript
+// GOOD
+try {
+  await saveData(data)
+} catch (error) {
+  logger.error('Failed to save data', { error, data })
+  throw new UserFacingError('Unable to save. Please try again.')
+}
+```
+
+---
+
+### 3. DON'T Use Nested Ternaries
+
+**Problem**: Deeply nested ternary operators are hard to read and maintain.
+
+```typescript
+// BAD - Unreadable nested ternaries
+const status = isLoading ? 'loading' : hasError ? 'error' : isComplete ? 'complete' : 'idle'
+
+// BAD - Even worse with more nesting
+const message = !user ? 'Not logged in' : !user.verified ? 'Please verify' : user.isPremium ? 'Welcome back, premium user!' : 'Welcome back!'
+```
+
+**Why This is Wrong**:
+
+- Extremely hard to read and understand
+- Easy to introduce bugs when modifying
+- Difficult to add new conditions
+
+**Fix**: Use if/else statements, switch statements, or lookup objects.
+
+```typescript
+// GOOD - Clear and maintainable
+function getStatus(isLoading: boolean, hasError: boolean, isComplete: boolean) {
+  if (isLoading) return 'loading'
+  if (hasError) return 'error'
+  if (isComplete) return 'complete'
+  return 'idle'
+}
+```
+
+---
+
+### 4. DON'T Mutate Function Parameters
+
+**Problem**: Mutating parameters causes unexpected side effects and makes code unpredictable.
+
+```typescript
+// BAD - Mutating the input array
+function addItem(items: string[], newItem: string) {
+  items.push(newItem) // Modifies the original array!
+  return items
+}
+
+// BAD - Mutating object properties
+function updateUser(user: User) {
+  user.lastUpdated = new Date() // Modifies the original object!
+  return user
+}
+```
+
+**Why This is Wrong**:
+
+- Caller doesn't expect their data to change
+- Causes bugs that are hard to track down
+- Breaks immutability expectations in React/Redux
+
+**Fix**: Return new objects/arrays instead of mutating.
+
+```typescript
+// GOOD - Returns new array
+function addItem(items: string[], newItem: string) {
+  return [...items, newItem]
+}
+
+// GOOD - Returns new object
+function updateUser(user: User) {
+  return { ...user, lastUpdated: new Date() }
+}
+```
+
+---
+
+### 5. DON'T Mix Async Patterns
+
+**Problem**: Mixing callbacks, promises, and async/await makes code confusing and error-prone.
+
+```typescript
+// BAD - Mixing callbacks and promises
+function fetchData(callback) {
+  fetch('/api/data')
+    .then(res => res.json())
+    .then(data => callback(null, data))
+    .catch(err => callback(err))
+}
+
+// BAD - Mixing .then() with async/await
+async function processData() {
+  const result = await fetchData()
+  return result.then(data => transform(data)) // Mixing patterns!
+}
+```
+
+**Why This is Wrong**:
+
+- Confusing control flow
+- Error handling becomes inconsistent
+- Harder to debug and maintain
+
+**Fix**: Use async/await consistently throughout.
+
+```typescript
+// GOOD - Consistent async/await
+async function fetchData() {
+  const response = await fetch('/api/data')
+  return response.json()
+}
+
+async function processData() {
+  const data = await fetchData()
+  return transform(data)
+}
+```
+
+---
+
+## Adding Your Anti-Patterns
+
+When adding new anti-patterns to this file:
+
+1. **Start with "DON'T"** followed by the pattern name
+2. **Describe the problem** briefly
+3. **Provide BAD examples** showing the anti-pattern
+4. **Explain why it's wrong** with a bullet list
+5. **Show the fix** or reference `.cursor/rules/core/allowed-patterns.mdc`
+
+---
+
+## Template for New Anti-Patterns
+
+```markdown
+### DON'T: Pattern Name
+
+**Problem**: Brief description of why this is problematic.
+
+\`\`\`typescript
+// BAD - Example of the anti-pattern
+const badExample = problematicCode()
+\`\`\`
+
+**Why This is Wrong**:
+
+- Reason 1
+- Reason 2
+
+**Fix**: Description or link to `.cursor/rules/core/allowed-patterns.mdc`.
+```

package/rules/core/project-ledger.mdc

@@ -0,0 +1,155 @@
+---
+description: "Persistent project learning journal - always active to maintain institutional memory across sessions"
+alwaysApply: true
+---
+
+# Project Ledger
+
+## Purpose
+
+A persistent, project-specific learning journal maintained across sessions. The ledger captures mistakes, corrections, discovered patterns, and hard-won knowledge about a specific codebase - building institutional memory that compounds over time.
+
+**Location**: `flow/ledger.md`
+
+---
+
+## Behavior
+
+### On Session Start
+
+1. Check if `flow/ledger.md` exists
+2. If it exists, read it and internalize the learnings silently
+3. If it doesn't exist and the `flow/` directory exists, create it using the template below
+4. Apply all recorded learnings naturally - never announce "I read the ledger" or reference it unless asked
+
+### During Work
+
+Record entries as soon as you learn something worth remembering. Don't batch updates for the end of a session - write them while the context is fresh.
+
+**Update the ledger when you:**
+
+- Get corrected by the user on something project-specific
+- Discover an undocumented project quirk or constraint
+- Find that an approach doesn't work in this codebase (and why)
+- Learn a user preference for how they like things done
+- Successfully navigate a tricky problem unique to this project
+- Notice a gap between documented patterns and actual codebase behavior
+- Encounter environment-specific gotchas (build issues, tool configs, etc.)
+- Learn domain-specific terminology or business rules
+
+### What NOT to Record
+
+- Generic programming knowledge (that's what rules files are for)
+- Patterns already documented in rules files
+- Temporary issues that won't recur
+- Information that belongs in a discovery document or plan
+
+---
+
+## Entry Format
+
+Each entry should be concise and actionable. Write entries as lessons, not as narratives.
+
+**Good entries:**
+- "The `buildWidgets` script requires Node 18+ - fails silently on Node 16"
+- "User prefers explicit error types over generic Error class"
+- "API responses from /legacy/* endpoints use snake_case despite the rest being camelCase"
+- "Tests for streaming endpoints need a 3s timeout override - default 5s causes CI flakiness"
+
+**Bad entries:**
+- "Had a good session today" (not actionable)
+- "JavaScript uses === for strict equality" (generic knowledge)
+- "Fixed a bug in user service" (too vague, no lesson)
+
+---
+
+## Ledger Sections
+
+### Project Quirks
+
+Things that are unique or surprising about this specific project. Build config gotchas, undocumented dependencies between modules, services that behave differently than expected.
+
+### What Works
+
+Approaches and solutions that proved effective in this project. Patterns that solved recurring problems. Techniques the user approved of.
+
+### What Didn't Work
+
+Approaches that were tried and failed, with brief explanation of why. This prevents repeating the same mistakes across sessions.
+
+### User Preferences
+
+How the user likes things done. Communication style, code style preferences beyond what's in rules files, workflow preferences, conventions they care about.
+
+### Domain Context
+
+Business logic, domain terminology, and project-specific concepts that affect technical decisions. Things that aren't obvious from reading the code alone.
+
+---
+
+## Template
+
+When creating `flow/ledger.md` for the first time, use this structure:
+
+```markdown
+# Project Ledger
+
+> Persistent learning journal - updated automatically across sessions.
+> Last updated: {date}
+
+## Project Quirks
+
+<!-- Unexpected behaviors, environment gotchas, undocumented constraints -->
+
+## What Works
+
+<!-- Proven approaches and solutions for this project -->
+
+## What Didn't Work
+
+<!-- Failed approaches with brief "why" so we don't repeat them -->
+
+## User Preferences
+
+<!-- How the user likes things done beyond what rules files capture -->
+
+## Domain Context
+
+<!-- Business logic, terminology, and concepts that affect decisions -->
+```
+
+---
+
+## Maintenance Rules
+
+1. **Keep it under 150 lines** of high-signal content
+2. **Consolidate periodically**: After every 8-10 sessions, merge similar entries, remove outdated ones, and promote recurring corrections to standing guidelines
+3. **Remove stale entries**: If a quirk gets fixed or a constraint is lifted, remove the entry
+4. **Promote to rules**: If a preference or pattern becomes well-established, move it to the appropriate rules file and remove from the ledger
+5. **No duplicates**: Before adding an entry, scan existing entries to avoid redundancy
+
+---
+
+## Integration with Plan-Flow Workflow
+
+The ledger naturally captures learnings from plan-flow activities:
+
+| Activity | What Gets Captured |
+|----------|-------------------|
+| `/setup` | Environment surprises, toolchain quirks |
+| `/discovery-plan` | Domain context, business rules learned from user |
+| `/execute-plan` | What worked/didn't during implementation |
+| `/review-code` | Pattern conflicts discovered, user feedback on style |
+| `/review-pr` | Recurring review issues, team conventions |
+
+The ledger is **not** a replacement for plan-flow artifacts. Discovery documents, plans, and reviews remain in their respective folders. The ledger captures the meta-learnings that span across activities.
+
+---
+
+## Rules
+
+1. **Silent by default**: Never tell the user "I updated the ledger" unless they ask about it
+2. **Immediate writes**: Record learnings as they happen, don't wait
+3. **Lessons over logs**: Write what you learned, not what you did
+4. **Project-specific only**: Only record things unique to this project
+5. **Honest self-correction**: Record your own mistakes, not just user corrections