PROJECT_STATE.md Template

Copy this template to your code repository root as PROJECT_STATE.md.

Template

# HRMS Project State

**Last Updated:** YYYY-MM-DD HH:MM UTC
**Current Phase:** XX (Phase Name)
**Current Step:** XX of YY
**Progress:** XX% of current phase

---

## Session Context

**Session Started:** YYYY-MM-DD HH:MM
**Working On:** Step XX - Description

### Last Completed Step
- **Step XX:** Description
- **Gate Passed:** Gate criteria verified
- **Files Modified:** list of files
- **Files Now Locked:** list of newly locked files

### Current Step
- **Step XX:** Description
- **Status:** IN PROGRESS / BLOCKED / WAITING
- **Expected Files:** files to be created/modified
- **Blockers:** any blockers (or "None")

### What I'm About To Do
Brief description of the next action. This helps the next session understand context.

---

## Completed Phases (DO NOT MODIFY THESE FILES)

<!-- 
List completed phases here as they are finished.
Example:
### Phase 00: Empty Shell ✅
- **Completed:** YYYY-MM-DD
- **Git Tag:** phase-00-empty-shell
- **Locked Files:**
  - list files...
- **Key Decisions:**
  - list decisions...
-->

[No phases completed yet]


---

## Current Phase: XX - Phase Name

### Phase Goal
Brief description of what this phase accomplishes.

### Completed Steps
- [x] Step XX: Description ✅ (HH:MM)
- [x] Step XX: Description ✅ (HH:MM)
- [x] Step XX: Description ✅ (HH:MM)

### Current Step
- [ ] Step XX: Description (IN PROGRESS)

### Remaining Steps
- [ ] Step XX: Description
- [ ] Step XX: Description
- [ ] Step XX: Description

### Phase Completion Gate
- [ ] Gate criteria 1
- [ ] Gate criteria 2
- [ ] All tests passing

---

## Quick Status Table

| Phase | Steps | Status | Git Tag |
|-------|-------|--------|---------|
| 00 Empty Shell | 01-08 | ⏳ Pending | - |
| 01 Multi-Tenant Auth | 09-31 | ⏳ Pending | - |
| 01.5 Design System | 32-40 | ⏳ Pending | - |
| 02 Employee Entity | 41-60 | ⏳ Pending | - |
| 03 Org Structure | 61-85 | ⏳ Pending | - |
| 04 Org Chart | 86-100 | ⏳ Pending | - |
| 05 Time-Off | 101-130 | ⏳ Pending | - |

---

## Session Log

| Date | Time | Action | Step | Notes |
|------|------|--------|------|-------|
| YYYY-MM-DD | HH:MM | Started session | Step XX | Initial context |
| YYYY-MM-DD | HH:MM | Completed Step XX | Step XX | Gate passed |
| YYYY-MM-DD | HH:MM | Completed Step XX | Step XX | Gate passed |
| YYYY-MM-DD | HH:MM | Paused session | Step XX | Handoff note: ... |
| YYYY-MM-DD | HH:MM | Resumed session | Step XX | Continuing from ... |

---

## Active Decisions (ADRs)

| ADR | Decision | Phase | Rationale |
|-----|----------|-------|-----------|
| | | | |

---

## NEVER DO (Read Before Every Action)

<Callout type="error">
Read this section at the start of EVERY session.
</Callout>

- ❌ **NEVER** modify files in "Locked Files" lists without ADR
- ❌ **NEVER** skip gates - every step has a verification
- ❌ **NEVER** add features not in current phase specification
- ❌ **NEVER** install packages not in technology stack
- ❌ **NEVER** start new phase before current phase complete
- ❌ **NEVER** suggest "improvements" to working code
- ❌ **NEVER** create new patterns if one exists (copy exactly)
- ❌ **NEVER** proceed without explicit user approval

---

## Error Log

### [Date] Error Description
- **Step:** XX
- **Error:** What went wrong
- **Resolution:** How it was fixed
- **Prevention:** What to avoid next time

---

## Notes for Next Session

- Important context point 1
- Important context point 2
- Files that need attention
- Decisions pending user input

Update Rules

After EVERY Step (~30 seconds)

Mark step as ✅ with timestamp
Update "Current Step" section
Add any new locked files
Update progress percentage

At Session End

Add entry to Session Log
Update "What I'm About To Do" for next session
Note any blockers
Add "Notes for Next Session"

At Phase Completion

Move phase to "Completed Phases" section
List ALL locked files from this phase
Document key decisions made
Create git tag: git tag phase-XX-name
Update Quick Status Table
Commit: git commit -m "Phase XX: [Name] complete"

Usage Example

Here's how PROJECT_STATE.md evolves during a session:

Before Session (Read This)

**Current Step:** Step 45 - Create Employee Service
**Last Completed:** Step 44 - Create Employee Model
**What I'm About To Do:** Implement EmployeeService with CRUD operations

During Session (Update After Each Step)

### Completed Steps
- [x] Step 44: Create Employee Model ✅ (09:30)
- [x] Step 45: Create Employee Service ✅ (10:15)

### Current Step
- [ ] Step 46: Create Employee Controller (IN PROGRESS)

End of Session (Write Handoff)

### What I'm About To Do
Complete Employee Controller with GET /employees and POST /employees.
Pattern source: tenant.controller.ts

### Notes for Next Session
- EmployeeService follows TenantService pattern
- Need to add tenantId filtering to all queries
- Gate: npm test employee.controller passes

PROJECT_STATE.md Template

On this page