plan-flow-skill 1.0.0

package/rules/patterns/contract-patterns.mdc

@@ -0,0 +1,344 @@
+---
+description: "Patterns for creating and maintaining integration contracts"
+alwaysApply: false
+---
+
+# Contract Patterns
+
+## Overview
+
+This document defines patterns for creating integration contracts. Contracts document how the frontend integrates with external services, APIs, or backend systems.
+
+---
+
+## Contract Types
+
+| Type | Purpose | When to Use |
+|------|---------|-------------|
+| API Contract | REST/GraphQL endpoint documentation | Integrating with external APIs |
+| Integration Contract | Service connection details | Connecting to third-party services |
+| Component Contract | Props, events, data flow | Documenting component interfaces |
+
+---
+
+## Contract Document Structure
+
+Every contract should include these sections:
+
+### Required Sections
+
+1. **Overview**: Brief description of the service
+2. **Source**: URL and type (docs/repo)
+3. **Authentication**: How to authenticate requests
+4. **Base Configuration**: URLs, rate limits, timeouts
+5. **Endpoints**: Available API endpoints with schemas
+6. **Error Handling**: Error codes and response formats
+
+### Recommended Sections
+
+7. **FE Integration Notes**: Frontend-specific guidance
+8. **Usage Examples**: Code examples for common use cases
+9. **Webhooks**: Event subscriptions if applicable
+10. **Rate Limits**: Throttling information
+11. **Changelog**: Version history
+
+---
+
+## Allowed Patterns
+
+### 1. Use TypeScript Interfaces for Schemas
+
+Define request and response types using TypeScript interfaces:
+
+```typescript
+interface CreateUserRequest {
+  email: string;
+  name: string;
+  role?: 'admin' | 'user';
+}
+
+interface CreateUserResponse {
+  id: string;
+  email: string;
+  name: string;
+  createdAt: string;
+}
+```
+
+### 2. Document All Status Codes
+
+List all possible HTTP status codes with their meaning:
+
+| Code | Meaning | FE Action |
+|------|---------|-----------|
+| 200 | Success | Process response |
+| 201 | Created | Navigate to new resource |
+| 400 | Bad Request | Show validation errors |
+| 401 | Unauthorized | Redirect to login |
+| 403 | Forbidden | Show permission error |
+| 404 | Not Found | Show not found UI |
+| 429 | Rate Limited | Retry with backoff |
+| 500 | Server Error | Show generic error |
+
+### 3. Include Authentication Examples
+
+Provide complete authentication setup:
+
+```typescript
+// API Key Authentication
+const headers = {
+  'X-API-Key': process.env.API_KEY,
+  'Content-Type': 'application/json',
+};
+
+// Bearer Token Authentication
+const headers = {
+  'Authorization': `Bearer ${accessToken}`,
+  'Content-Type': 'application/json',
+};
+
+// OAuth2 Flow
+async function getAccessToken(): Promise<string> {
+  const response = await fetch(TOKEN_URL, {
+    method: 'POST',
+    body: new URLSearchParams({
+      grant_type: 'client_credentials',
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+    }),
+  });
+  const { access_token } = await response.json();
+  return access_token;
+}
+```
+
+### 4. Define Error Response Types
+
+Create typed error handling:
+
+```typescript
+interface ApiError {
+  code: string;
+  message: string;
+  details?: Record<string, string[]>;
+}
+
+function handleError(error: ApiError): void {
+  switch (error.code) {
+    case 'VALIDATION_ERROR':
+      // Show field-specific errors
+      break;
+    case 'UNAUTHORIZED':
+      // Clear auth and redirect
+      break;
+    case 'RATE_LIMITED':
+      // Queue for retry
+      break;
+    default:
+      // Show generic error
+  }
+}
+```
+
+### 5. Document Rate Limit Handling
+
+Include retry logic patterns:
+
+```typescript
+async function fetchWithRetry<T>(
+  url: string,
+  options: RequestInit,
+  maxRetries = 3
+): Promise<T> {
+  for (let i = 0; i < maxRetries; i++) {
+    const response = await fetch(url, options);
+    
+    if (response.status === 429) {
+      const retryAfter = response.headers.get('Retry-After') || '1';
+      await delay(parseInt(retryAfter) * 1000);
+      continue;
+    }
+    
+    if (!response.ok) {
+      throw new ApiError(await response.json());
+    }
+    
+    return response.json();
+  }
+  throw new Error('Max retries exceeded');
+}
+```
+
+---
+
+## Forbidden Patterns
+
+### 1. DON'T Hardcode Credentials
+
+Never include actual API keys or secrets in contracts:
+
+```typescript
+// BAD
+const API_KEY = 'sk_live_abc123';
+
+// GOOD
+const API_KEY = process.env.STRIPE_API_KEY;
+```
+
+### 2. DON'T Skip Error Documentation
+
+Always document error scenarios:
+
+```markdown
+// BAD - No error handling documented
+## Endpoints
+### GET /users
+Returns list of users.
+
+// GOOD - Error cases documented
+## Endpoints
+### GET /users
+Returns list of users.
+
+**Error Responses**:
+- 401: Invalid or expired token
+- 403: Insufficient permissions
+- 429: Rate limit exceeded
+```
+
+### 3. DON'T Use Generic Types
+
+Be specific with type definitions:
+
+```typescript
+// BAD
+interface Response {
+  data: any;
+  meta: object;
+}
+
+// GOOD
+interface UserListResponse {
+  data: User[];
+  meta: {
+    total: number;
+    page: number;
+    perPage: number;
+  };
+}
+```
+
+### 4. DON'T Omit Required Fields
+
+Mark required vs optional clearly:
+
+```typescript
+// BAD - Unclear requirements
+interface CreateUserRequest {
+  email: string;
+  name: string;
+  phone: string;
+}
+
+// GOOD - Optional fields marked
+interface CreateUserRequest {
+  email: string;      // Required
+  name: string;       // Required
+  phone?: string;     // Optional
+}
+```
+
+---
+
+## FE Integration Guidelines
+
+### State Management Recommendations
+
+| Data Type | Recommendation |
+|-----------|----------------|
+| User session | Global store (Zustand/Redux) |
+| API responses | React Query / SWR |
+| Form state | Local component state |
+| UI state | Local or context |
+
+### Loading State Patterns
+
+```typescript
+type RequestState<T> =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: T }
+  | { status: 'error'; error: ApiError };
+```
+
+### Caching Recommendations
+
+| Endpoint Type | Cache Strategy |
+|---------------|----------------|
+| List endpoints | Cache with revalidation |
+| Detail endpoints | Cache by ID |
+| Mutations | Invalidate related queries |
+| Real-time data | No cache / short TTL |
+
+---
+
+## Contract Maintenance
+
+### When to Update Contracts
+
+- API version changes
+- New endpoints added
+- Breaking changes in schemas
+- Authentication method changes
+- Rate limit adjustments
+
+### Version Tracking
+
+Include changelog in contracts:
+
+```markdown
+## Changelog
+
+| Date | Version | Changes |
+|------|---------|---------|
+| 2024-01-15 | 2.0 | Added pagination to list endpoints |
+| 2024-01-10 | 1.1 | Added webhook documentation |
+| 2024-01-01 | 1.0 | Initial contract |
+```
+
+---
+
+## Contract File Organization
+
+```
+contracts/
+├── stripe_payments_contract.md
+├── auth0_authentication_contract.md
+├── sendgrid_email_contract.md
+├── openai_chat_contract.md
+└── internal_api_contract.md
+```
+
+### Naming Convention
+
+`<service_name>_<feature>_contract.md`
+
+Examples:
+- `stripe_payments_contract.md`
+- `stripe_subscriptions_contract.md`
+- `github_repos_contract.md`
+
+---
+
+## Summary
+
+| Pattern | Description |
+|---------|-------------|
+| TypeScript Interfaces | Use typed schemas for requests/responses |
+| Status Code Documentation | Document all HTTP status codes |
+| Authentication Examples | Provide complete auth setup code |
+| Error Type Definitions | Create typed error handling |
+| Rate Limit Handling | Include retry logic patterns |
+| No Hardcoded Secrets | Use environment variables |
+| Specific Types | Avoid `any` and `object` |
+| Required Field Markers | Mark optional fields explicitly |

package/rules/patterns/discovery-patterns.mdc

@@ -0,0 +1,354 @@
+---
+description: "Discovery patterns for gathering requirements before implementation planning"
+alwaysApply: false
+---
+
+# Discovery Patterns
+
+## Overview
+
+This document defines the patterns and rules for creating discovery documents. For step-by-step execution, see the `/discovery-plan` command. For document templates, see `.cursor/rules/patterns/discovery-templates.mdc`.
+
+---
+
+## What is Discovery?
+
+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
+
+**Workflow**: Discovery Output → Implementation Plan → Execution
+
+---
+
+## Folder Structure
+
+```
+flow/
+├── archive/                    # IGNORE - Completed/abandoned documents
+├── discovery/                  # Active discovery documents
+│   ├── discovery_user_auth_v1.md
+│   ├── discovery_realtime_notifications_v1.md
+│   └── spike_streaming_performance_v1.md
+├── plans/                      # Implementation plans (created after discovery)
+│   └── plan_feature_v1.md
+├── contracts/                  # Integration contracts
+│   └── api_contract.md
+└── references/                 # Reference materials (specs, designs)
+    ├── api-specs.md
+    └── sse-events.md
+```
+
+**Critical**: NEVER read or reference files in `flow/archive/` - these are outdated documents.
+
+---
+
+## Naming Conventions
+
+| Prefix       | Purpose                   | When to Use                            |
+| ------------ | ------------------------- | -------------------------------------- |
+| `discovery_` | General feature discovery | Exploring a new feature or enhancement |
+| `spike_`     | Technical investigation   | Testing technical feasibility          |
+| `research_`  | In-depth research         | Comparing options or technologies      |
+
+**Format**: `<prefix>_<topic>_v<version>.md`
+
+**Examples**:
+
+- `discovery_workflow_editor_v1.md`
+- `spike_sse_performance_v1.md`
+- `research_state_management_v1.md`
+
+---
+
+## Question Status Tracking
+
+Track every question with a clear status:
+
+| Status   | Meaning                                       | Action Required          |
+| -------- | --------------------------------------------- | ------------------------ |
+| Open     | Waiting for user response                     | Wait for answer          |
+| Answered | User provided answer                          | Document in requirements |
+| Assumed  | Made reasonable assumption (needs validation) | Request validation       |
+| Blocked  | Cannot proceed without answer                 | Escalate to user         |
+
+**Question Table Format**:
+
+```markdown
+| #   | Category   | Question                   | Status   | Answer            |
+| --- | ---------- | -------------------------- | -------- | ----------------- |
+| 1   | Functional | Max steps per workflow?    | Answered | 20 steps maximum  |
+| 2   | Technical  | Use existing store or new? | Open     | -                 |
+| 3   | NFR        | Required response time?    | Assumed  | <500ms (validate) |
+```
+
+---
+
+## Requirements Categories
+
+Categorize all gathered requirements:
+
+| Category    | Prefix | Description                               |
+| ----------- | ------ | ----------------------------------------- |
+| Functional  | FR-    | What the feature must do                  |
+| Non-Functional | NFR- | Performance, security, scalability        |
+| Constraints | C-     | Limitations, dependencies, boundaries     |
+| Acceptance  | AC-    | How we know the feature is complete       |
+
+**Format**:
+
+```markdown
+- [FR-1]: Users can create workflow steps with title and content
+- [NFR-1]: Step creation should complete within 500ms
+- [C-1]: Must use existing authentication flow
+```
+
+---
+
+## Allowed Patterns
+
+### 1. Read All Referenced Documents First
+
+**Always** read every referenced document before asking questions.
+
+**Process**:
+
+1. Identify referenced files (look for @mentions, file paths)
+2. Read all referenced files using the Read tool
+3. Extract relevant requirements, constraints, contracts
+4. Document findings with key points
+5. Then ask questions about gaps or unclear aspects
+
+---
+
+### 2. Ask Questions Using Interactive Questions Tool
+
+**Use Plan mode's Questions UI** for a better user experience.
+
+**Process**:
+
+1. Call `SwitchMode` tool to enter Plan mode
+2. Call `AskQuestion` tool for each question
+3. Wait for responses
+4. Call `SwitchMode` tool to return to Agent mode
+
+See `.cursor/rules/tools/interactive-questions-tool.mdc` for detailed instructions.
+
+**Question Format**:
+
+- Use 2-6 multiple-choice options per question
+- Label options with A, B, C, D, E, F
+- Provide context in the explanation parameter
+- Ask all questions in one Plan mode session
+
+---
+
+### 3. Structure Discovery Documents Consistently
+
+Every discovery document must include these sections:
+
+| Section                  | Purpose                                    |
+| ------------------------ | ------------------------------------------ |
+| Context                  | Why this discovery is needed               |
+| Referenced Documents     | Documents reviewed with key findings       |
+| Requirements Gathered    | FR, NFR, Constraints categorized           |
+| Open Questions           | Tracked with status                        |
+| Technical Considerations | Architecture, dependencies, patterns       |
+| Proposed Approach        | High-level recommendation (NOT code)       |
+| Risks and Unknowns       | Identified risks with mitigation           |
+| Next Steps               | Follow-up actions linking to `/create-plan` |
+
+See `.cursor/rules/patterns/discovery-templates.mdc` for the full template.
+
+---
+
+### 4. Mark Assumptions Explicitly
+
+When making assumptions, always mark them clearly:
+
+```markdown
+| 3 | NFR | Required response time? | Assumed | <500ms (needs validation) |
+```
+
+**Process**:
+
+1. Mark with "Assumed" status
+2. Note the assumption clearly
+3. Request validation from user
+4. Update to "Answered" once confirmed
+
+---
+
+### 5. Keep Discovery High-Level
+
+Focus on "what" not "how". Discovery captures:
+
+- **What** the feature should do
+- **What** constraints exist
+- **What** risks are present
+- **What** approach is recommended
+
+Implementation details belong in the plan, not discovery.
+
+---
+
+### 6. Link Discovery to Plan
+
+When discovery is complete:
+
+1. Reference the discovery document in the plan's Overview
+2. Move discovery to `flow/archive/` after plan execution
+
+```markdown
+## Overview
+
+This plan implements the feature described in the discovery document:
+`flow/discovery/discovery_workflow_editor_v1.md`
+```
+
+---
+
+## Forbidden Patterns
+
+### 1. DON'T Skip Reading Referenced Documents
+
+**Problem**: Making assumptions without reviewing available context leads to incorrect implementations.
+
+**Fix**: Always read referenced files before asking questions.
+
+---
+
+### 2. DON'T Make Assumptions Without Marking Them
+
+**Problem**: Assumptions presented as facts cause incorrect implementations.
+
+**Fix**: Mark assumptions with "Assumed" status and request validation.
+
+---
+
+### 3. DON'T Create Plans Without Discovery for Complex Features
+
+**Problem**: Jumping to planning without understanding leads to rework.
+
+**Fix**: For features with unknowns, always do discovery first.
+
+---
+
+### 4. DON'T Proceed with Blocked Questions
+
+**Problem**: Moving forward with unresolved blockers creates problems later.
+
+**Fix**: Resolve blocked questions before proposing approach.
+
+---
+
+### 5. DON'T Mix Discovery Documents with Plans
+
+**Problem**: Confusion about document purpose.
+
+**Fix**: Keep discovery in `flow/discovery/`, plans in `flow/plans/`.
+
+---
+
+### 6. DON'T Write Implementation Details in Discovery
+
+**Problem**: Discovery should focus on "what", not "how".
+
+**Fix**: Keep discovery at the conceptual level. Implementation belongs in the plan.
+
+---
+
+### 7. DON'T Write Code During Discovery
+
+**Problem**: Discovery is for gathering information, not implementing.
+
+**Forbidden Actions**:
+
+- Creating or editing source files (`.ts`, `.tsx`, `.js`, etc.)
+- Modifying configuration files
+- Running code generation commands
+- Making any changes to the codebase
+- Writing implementation code in responses
+
+**Allowed Actions**:
+
+- Reading files to understand current implementation
+- Searching codebase for context
+- Asking questions
+- Creating the discovery markdown document
+
+---
+
+### 8. DON'T Create Discovery for Trivial Features
+
+**Problem**: Overhead without value for simple changes.
+
+**When to Skip Discovery**:
+
+- Single-file changes
+- Clear, well-defined requirements
+- No unknowns or ambiguity
+- Similar to existing implementations
+
+**Fix**: Use discovery only when there's genuine uncertainty to resolve.
+
+---
+
+## When to Ask vs. When to Document
+
+### ASK When:
+
+- Requirements are vague or ambiguous
+- Technical approach is unclear
+- Multiple valid interpretations exist
+- Dependencies or constraints are unknown
+- Acceptance criteria are not defined
+- Edge cases are not specified
+
+### DOCUMENT When:
+
+- Information is clear in referenced documents
+- User has provided explicit answer
+- Standard pattern applies (per cursor rules)
+- Similar feature exists in codebase
+- Assumption has been validated
+
+---
+
+## Discovery Document Output
+
+The discovery document is the **ONLY** deliverable. It must be:
+
+1. **Saved** in `flow/discovery/` folder
+2. **Named** using convention: `discovery_<feature>_v<version>.md`
+3. **Complete** with all required sections
+4. **Reviewed** by user before plan creation
+5. **Linked** to the implementation plan
+
+---
+
+## Related Resources
+
+- **Command**: `/discovery-plan` - Orchestrates the discovery workflow
+- **Templates**: `.cursor/rules/patterns/discovery-templates.mdc`
+- **Interactive Questions**: `.cursor/rules/tools/interactive-questions-tool.mdc`
+- **Plan Command**: `/create-plan` - Creates plan from discovery
+
+---
+
+## Summary
+
+| Pattern                        | Description                                    |
+| ------------------------------ | ---------------------------------------------- |
+| Read documents first           | Always review referenced files before asking   |
+| Use interactive questions      | Plan mode Questions UI for better UX           |
+| Structure consistently         | Follow the standard discovery template         |
+| Mark assumptions               | Always label and validate assumptions          |
+| Stay high-level                | Focus on "what" not "how"                      |
+| Link to plan                   | Reference discovery in plan overview           |
+| No code                        | Only create the discovery markdown file        |
+| Skip for trivial features      | Don't over-engineer simple changes             |