Maintains comprehensive project history in process-notes.md that documents work process, decisions, dead ends, and progress. Use when context window fills up (approaching 60% of token budget), when making key decisions or reaching milestones, or when user explicitly requests /process-notes command.
From project-docsnpx claudepluginhub ttorres33/teresa-torres-plugins --plugin project-docsThis skill is limited to using the following tools:
Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Maintain a comprehensive project history in process-notes.md that documents our work process, decisions, dead ends, and progress. This creates a complete record that helps remember key decisions and provides full context for what happened and when.
Update process-notes.md when any of these conditions occur:
/process-notes commandprocess-notes.md first to understand recent entries and append new entriesUse this exact structure for each entry:
## [YYYY-MM-DD HH:MM] Entry N: [Brief Title]
**Context:** [Brief statement of what we were working on in this session/segment]
**Progress:**
- Accomplished task 1
- Created `src/auth/login.ts` - implemented JWT authentication
- Modified `src/config/database.ts:45-67` - added connection pooling
- Accomplished task 2
- Details with file references
**Key Decisions:**
- **Decision:** [What was decided]
- **Rationale:** [Why we chose this approach]
- **Alternatives considered:** [What else we looked at]
- **Trade-offs:** [What we gained/sacrificed]
- **Files affected:** `path/to/file.ts:lines`
**Dead Ends & Lessons:**
- **Attempted:** [What we tried]
- **Implementation:** [Specific approach taken]
- **Files involved:** `path/to/file.ts:lines`
- **Error/Issue:** [What failed - include error messages if relevant]
- **Why it failed:** [Root cause analysis]
- **What we learned:** [Key takeaway]
- **Solution:** [What we did instead and why it worked]
**Technical Details:**
- New files created: [list with purpose]
- Files modified: [list with what changed]
- Dependencies added/removed: [package changes]
- Configuration changes: [environment, build configs, etc.]
**Next Steps:**
- [ ] Task 1 - [with enough context to understand what/why]
- [ ] Task 2 - [reference to relevant files/functions if helpful]
- **Context for next session:** [Anything the next agent needs to know to pick up smoothly]
**Questions/Blockers:**
- Open questions that need answering
- Blockers encountered that aren't resolved yet
---
src/auth/middleware.ts:1-45 - implemented JWT verification middleware with error handling"process-notes.md in the current working directory root# Project Process Notesfile.ts:lines## [2025-11-17 14:32] Entry 1: Initial Authentication System
**Context:** Setting up user authentication for the web application. Need JWT-based auth with refresh tokens.
**Progress:**
- Implemented core authentication system
- Created `src/auth/jwt.ts:1-120` - JWT token generation and validation utilities
- Created `src/auth/middleware.ts:1-67` - Express middleware for protecting routes
- Modified `src/server.ts:23-28` - integrated auth middleware into Express app
- Created `src/routes/auth.ts:1-89` - login/logout/refresh endpoints
**Key Decisions:**
- **Decision:** Use JWT with short-lived access tokens (15min) + long-lived refresh tokens (7 days)
- **Rationale:** Balances security (short access token expiry) with UX (don't force frequent re-login)
- **Alternatives considered:** Session-based auth (rejected - doesn't scale horizontally), long-lived JWTs only (rejected - security risk)
- **Trade-offs:** Added complexity of refresh token flow, but gained better security posture
- **Files affected:** `src/auth/jwt.ts:45-89`, `src/routes/auth.ts:34-67`
**Dead Ends & Lessons:**
- **Attempted:** Store refresh tokens in localStorage
- **Implementation:** Added refresh token to JWT payload, stored in localStorage on client
- **Files involved:** `src/auth/jwt.ts:23-34`
- **Error/Issue:** Realized this is vulnerable to XSS attacks - localStorage accessible to any script
- **Why it failed:** Security best practice is httpOnly cookies for refresh tokens to prevent XSS access
- **What we learned:** Never store sensitive tokens in localStorage, use httpOnly cookies instead
- **Solution:** Implemented refresh token in httpOnly cookie in `src/routes/auth.ts:56-62`, removed from JWT payload
**Technical Details:**
- New files created:
- `src/auth/jwt.ts` - JWT utilities (sign, verify, decode)
- `src/auth/middleware.ts` - Express auth middleware
- `src/routes/auth.ts` - Auth endpoints
- `src/types/auth.ts` - TypeScript types for auth
- Files modified:
- `src/server.ts:23-28` - integrated auth routes
- Dependencies added:
- `jsonwebtoken@9.0.2` - JWT signing/verification
- `@types/jsonwebtoken@9.0.3` - TypeScript types
- `cookie-parser@1.4.6` - Parse cookies for refresh token
- Configuration changes:
- Added `JWT_SECRET` and `JWT_REFRESH_SECRET` to `.env`
- Added `JWT_EXPIRY=15m` and `REFRESH_EXPIRY=7d` to config
**Next Steps:**
- [ ] Add password hashing with bcrypt in user registration flow - needs `src/routes/users.ts` implementation
- [ ] Implement token refresh endpoint - partially done in `src/routes/auth.ts:78-89`, needs testing
- [ ] Add rate limiting to login endpoint to prevent brute force attacks
- **Context for next session:** Auth system works for login/logout. Need to add user registration with password hashing, and test the refresh token flow end-to-end.
**Questions/Blockers:**
- Should we implement 2FA now or in a later iteration?
- Need to confirm password requirements (min length, complexity rules)
---
| Scenario | Process-Notes | README | Both? |
|---|---|---|---|
| Just added OAuth authentication | Yes - Document why we chose OAuth, what we tried first, implementation decisions | Yes - Update to show OAuth is now available, how to configure it | Both |
| Debugged tricky issue for 2 hours | Yes - Document the debugging journey, what we learned, the solution | No - Unless it changes how the project works or needs documentation | Process-Notes only |
| Refactored file structure but behavior unchanged | Maybe - If significant decisions were made about structure | Maybe - If file paths in docs need updating | Use judgment |
| Added new feature (e.g., export to CSV) | Yes - How we built it, libraries chosen, design decisions | Yes - Update features list, add usage example | Both |
| Changed API endpoint structure | Yes - Why we changed it, migration path, breaking change reasoning | Yes - Update API docs to reflect new structure | Both |
| Fixed bug that restores documented behavior | Maybe - Only if debugging revealed important insights | No - Behavior already documented correctly | Usually Process-Notes only |
| Added environment variable | Yes - Why we needed it, what we considered | Yes - Update configuration section | Both |
| Spent time researching library options | Yes - What we evaluated, pros/cons, final choice | No - Unless we actually added the library | Process-Notes only (until implementation) |
| Reorganized code but kept same public API | Maybe - If architectural decisions were made | No - Internal structure doesn't affect users | Usually Process-Notes only |
| Context window approaching 90% | Yes - Checkpoint current progress | No - Unless meaningful changes to document | Process-Notes only (checkpoint) |
| Completed major milestone | Yes - Document what we accomplished, decisions made | Maybe - If milestone adds/changes features | Process-Notes always, README if user-facing changes |
Update Process-Notes if:
Update README if:
Update both if:
Update neither if: