Context Engineering Just Made Our Typescript Vibe Coding Workflow Actually Predictable

1
### 🔄 Project Awareness & Context
2
- **Always read `PLANNING.md`** at the start of a new conversation to understand the project's architecture, goals, style, and constraints.
3
- **Check `TASK.md`** before starting a new task. If the task isn't listed, add it with a brief description and today's date.
4
- **Use consistent naming conventions, file structure, and architecture patterns** as described in `PLANNING.md`.
5
- **Use the project's package manager** (npm/yarn/pnpm) as specified in `package.json` for all operations.
6

7
### 🧱 Code Structure & Modularity
8
- **Never create a file longer than 300 lines of code.** If a file approaches this limit, refactor by splitting it into modules or helper files.
9
- **Organize code into clearly separated modules**, grouped by feature or responsibility.
10
  For applications this looks like:
11
    - `src/` - Main source code
12
    - `src/types/` - Type definitions and interfaces
13
    - `src/utils/` - Utility functions and helpers
14
    - `src/services/` - Business logic and external API integrations
15
    - `src/controllers/` - Route handlers (for Express/Fastify apps)
16
    - `src/middleware/` - Express/Fastify middleware
17
- **Use barrel exports** (`index.ts` files) to create clean import paths.
18
- **Use absolute imports** when configured in `tsconfig.json` paths.
19
- **Use environment variables** with proper validation (zod, joi, or similar).
20

21
### 🧪 Testing & Reliability
22
- **Always create tests for new features** using the project's testing framework (Jest, Vitest, etc.).
23
- **After updating any logic**, check whether existing tests need to be updated. If so, do it.
24
- **Tests should live in a `__tests__` folder** next to the code they test, or in a separate `tests/` directory.
25
  - Include at least:
26
    - 1 test for expected behavior
27
    - 1 edge case test
28
    - 1 error handling test
29
- **Use proper mocking** for external dependencies and APIs.
30

31
### ✅ Task Completion
32
- **Mark completed tasks in `TASK.md`** immediately after finishing them.
33
- Add new sub-tasks or TODOs discovered during development to `TASK.md` under a "Discovered During Work" section.
34

35
### 📎 Style & Conventions
36
- **Use TypeScript** with strict mode enabled.
37
- **Follow the project's ESLint and Prettier configurations**.
38
- **Use modern TypeScript features**: utility types, branded types, const assertions, etc.
39
- **Prefer `const` over `let`**, and avoid `var` entirely.
40
- **Use `async/await` over Promises** for better readability.
41
- **Write JSDoc comments for all public functions and classes**:
42
  ```typescript
43
  /**
44
   * Brief description of what the function does.
45
   * 
46
   * @param param1 - Description of the parameter
47
   * @param param2 - Description of the parameter
48
   * @returns Description of what is returned
49
   * @throws {ErrorType} Description of when this error is thrown
50
   */
51
  function example(param1: string, param2: number): Promise<Result> {
52
    // implementation
53
  }
54
  ```
55
- **Use proper error handling** with custom error classes when appropriate.
56
- **Prefer composition over inheritance** and favor functional programming patterns.
57

58
### 🔧 TypeScript Specific Rules
59
- **Always use strict type checking** - no `any` types unless absolutely necessary.
60
- **Use `unknown` instead of `any`** when the type is truly unknown.
61
- **Define proper interfaces and types** for all data structures.
62
- **Use generic types** to create reusable, type-safe components.
63
- **Leverage discriminated unions** for complex state management.
64
- **Use `readonly` for immutable data** and `const assertions` where appropriate.
65
- **Prefer type guards and assertion functions** over type assertions.
66

67
### 📚 Documentation & Explainability
68
- **Update `README.md`** when new features are added, dependencies change, or setup steps are modified.
69
- **Comment complex logic** and ensure everything is understandable to a mid-level developer.
70
- **When writing complex logic, add a `// Reason:` comment** explaining the why, not just the what.
71
- **Keep `package.json` scripts up to date** with proper descriptions.
72

73
### 🧠 AI Behavior Rules
74
- **Never assume missing context. Ask questions if uncertain.**
75
- **Never hallucinate libraries or packages** – only use known, verified npm packages.
76
- **Always confirm file paths and module names** exist before referencing them in code or tests.
77
- **Never delete or overwrite existing code** unless explicitly instructed to or if part of a task from `TASK.md`.
78
- **Always run linting and type checking** before marking tasks complete.
79
- **Use the correct package manager** as specified in the project (check `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`).
80

81
### 🔍 Validation Commands
82
- **Type checking**: `npx tsc --noEmit` or `npm run type-check`
83
- **Linting**: `npx eslint src/` or `npm run lint`
84
- **Testing**: `npm test` or `npm run test`
85
- **Building**: `npm run build`
86
- **Always run these commands** before considering a task complete.

1
import { Request, Response, NextFunction } from 'express';
2
import jwt from 'jsonwebtoken';
3
import { config } from '../config/environment';
4
import { UnauthorizedError } from '../utils/errors';
5

6
/**
7
 * JWT authentication middleware for protecting routes.
8
 * 
9
 * This example demonstrates:
10
 * - JWT token validation
11
 * - Request augmentation with user data
12
 * - Proper error handling
13
 * - TypeScript typing for Express middleware
14
 */
15

16
export interface JWTPayload {
17
  userId: string;
18
  email: string;
19
  iat: number;
20
  exp: number;
21
}
22

23
export interface AuthenticatedRequest extends Request {
24
  user: {
25
    id: string;
26
    email: string;
27
  };
28
}
29

30
/**
31
 * Middleware to authenticate JWT tokens.
32
 * Adds user information to request object if token is valid.
33
 */
34
export const authenticateToken = async (
35
  req: Request,
36
  res: Response,
37
  next: NextFunction
38
): Promise<void> => {
39
  try {
40
    // Extract token from Authorization header
41
    const authHeader = req.headers.authorization;
42
    const token = authHeader?.split(' ')[1]; // Bearer TOKEN
43

44
    if (!token) {
45
      throw new UnauthorizedError('No token provided');
46
    }
47

48
    // Verify token
49
    const payload = jwt.verify(token, config.JWT_SECRET) as JWTPayload;
50

51
    // Attach user information to request
52
    (req as AuthenticatedRequest).user = {
53
      id: payload.userId,
54
      email: payload.email,
55
    };
56

57
    next();
58
  } catch (error) {
59
    if (error instanceof jwt.JsonWebTokenError) {
60
      next(new UnauthorizedError('Invalid token'));
61
    } else if (error instanceof jwt.TokenExpiredError) {
62
      next(new UnauthorizedError('Token expired'));
63
    } else {
64
      next(error);
65
    }
66
  }
67
};
68

69
/**
70
 * Optional authentication middleware.
71
 * Adds user information if token is present and valid, but doesn't require it.
72
 */
73
export const optionalAuth = async (
74
  req: Request,
75
  res: Response,
76
  next: NextFunction
77
): Promise<void> => {
78
  try {
79
    const authHeader = req.headers.authorization;
80
    const token = authHeader?.split(' ')[1];
81

82
    if (token) {
83
      const payload = jwt.verify(token, config.JWT_SECRET) as JWTPayload;
84
      (req as AuthenticatedRequest).user = {
85
        id: payload.userId,
86
        email: payload.email,
87
      };
88
    }
89

90
    next();
91
  } catch (error) {
92
    // For optional auth, we ignore token errors and continue
93
    next();
94
  }
95
};
96

97
/**
98
 * Generate JWT access token.
99
 */
100
export const generateAccessToken = (userId: string, email: string): string => {
101
  return jwt.sign(
102
    { userId, email },
103
    config.JWT_SECRET,
104
    { expiresIn: config.JWT_EXPIRES_IN }
105
  );
106
};
107

108
/**
109
 * Generate JWT refresh token.
110
 */
111
export const generateRefreshToken = (userId: string): string => {
112
  return jwt.sign(
113
    { userId, type: 'refresh' },
114
    config.JWT_REFRESH_SECRET,
115
    { expiresIn: config.JWT_REFRESH_EXPIRES_IN }
116
  );
117
};

1
# Create PRP
2

3
## Feature file: $ARGUMENTS
4

5
Generate a complete PRP for TypeScript/Node.js feature implementation with thorough research. Ensure context is passed to the AI agent to enable self-validation and iterative refinement. Read the feature file first to understand what needs to be created, how the examples provided help, and any other considerations.
6

7
The AI agent only gets the context you are appending to the PRP and training data. Assume the AI agent has access to the codebase and the same knowledge cutoff as you, so it's important that your research findings are included or referenced in the PRP. The Agent has WebSearch capabilities, so pass URLs to documentation and examples.
8

9
## Research Process
10

11
1. **Codebase Analysis**
12
   - Search for similar features/patterns in the codebase
13
   - Identify files to reference in PRP
14
   - Note existing conventions to follow
15
   - Check test patterns for validation approach
16

17
2. **External Research**
18
   - Search for similar features/patterns online
19
   - Library documentation (include specific URLs)
20
   - Implementation examples (GitHub/StackOverflow/blogs)
21
   - Best practices and common pitfalls
22

23
3. **User Clarification** (if needed)
24
   - Specific patterns to mirror and where to find them?
25
   - Integration requirements and where to find them?
26

27
## PRP Generation
28

29
Using PRPs/templates/prp_base.md as template:
30

31
### Critical Context to Include and pass to the AI agent as part of the PRP
32
- **Documentation**: URLs with specific sections
33
- **Code Examples**: Real snippets from codebase
34
- **Gotchas**: Library quirks, version issues, TypeScript-specific issues
35
- **Patterns**: Existing approaches to follow
36

37
### Implementation Blueprint
38
- Start with pseudocode showing approach
39
- Reference real files for patterns
40
- Include error handling strategy
41
- List tasks to be completed to fulfill the PRP in the order they should be completed
42

43
### Validation Gates (Must be Executable) for TypeScript/Node.js
44
```bash
45
# Type checking
46
npx tsc --noEmit
47

48
# Linting
49
npm run lint
50

51
# Testing
52
npm test
53

54
# Building
55
npm run build
56
```
57

58
*** CRITICAL AFTER YOU ARE DONE RESEARCHING AND EXPLORING THE CODEBASE BEFORE YOU START WRITING THE PRP ***
59

60
*** ULTRATHINK ABOUT THE PRP AND PLAN YOUR APPROACH THEN START WRITING THE PRP ***
61

62
## Output
63
Save as: `PRPs/{feature-name}.md`
64

65
## Quality Checklist
66
- [ ] All necessary context included
67
- [ ] Validation gates are executable by AI
68
- [ ] References existing patterns
69
- [ ] Clear implementation path
70
- [ ] Error handling documented
71
- [ ] TypeScript-specific considerations included
72
- [ ] Modern Node.js patterns used
73

74
Score the PRP on a scale of 1-10 (confidence level to succeed in one-pass implementation using Claude Code)
75

76
Remember: The goal is one-pass implementation success through comprehensive context.

1
# Execute TypeScript PRP
2

3
Implement a TypeScript/Node.js feature using the PRP file.
4

5
## PRP File: $ARGUMENTS
6

7
## Execution Process
8

9
1. **Load PRP**
10
   - Read the specified PRP file
11
   - Understand all context and requirements
12
   - Follow all instructions in the PRP and extend the research if needed
13
   - Ensure you have all needed context to implement the PRP fully
14
   - Do more web searches and codebase exploration as needed
15

16
2. **ULTRATHINK**
17
   - Think hard before you execute the plan. Create a comprehensive plan addressing all requirements.
18
   - Break down complex tasks into smaller, manageable steps using your todos tools.
19
   - Use the TodoWrite tool to create and track your implementation plan.
20
   - Identify implementation patterns from existing code to follow.
21

22
3. **Execute the plan**
23
   - Execute the PRP
24
   - Implement all the code
25
   - Follow TypeScript best practices
26
   - Use proper error handling
27
   - Ensure type safety throughout
28

29
4. **Validate**
30
   - Run each validation command:
31
     - `npx tsc --noEmit` (type checking)
32
     - `npm run lint` (linting)
33
     - `npm test` (testing)
34
     - `npm run build` (building)
35
   - Fix any failures
36
   - Re-run until all pass
37

38
5. **Complete**
39
   - Ensure all checklist items done
40
   - Run final validation suite
41
   - Report completion status
42
   - Read the PRP again to ensure you have implemented everything
43

44
6. **Reference the PRP**
45
   - You can always reference the PRP again if needed
46

47
Note: If validation fails, use error patterns in PRP to fix and retry. Pay special attention to TypeScript compilation errors and ensure all types are properly defined.

1
git clone https://github.com/DwayneSamuels/typescript-context-engineering-template.git
2
cd typescript-context-engineering-template
3
cursor .