hrms/CLAUDE.md

hrms/.cursorrules

## Current Phase
**Phase 00: Empty Shell** (or your actual starting phase)

## Current Step
Step 1 of XX

## What I'm About To Do
Set up the monorepo structure following phase-00-empty-shell.mdx

Read these files in order:
1. PROJECT_STATE.md
2. WHAT_EXISTS.md

Then tell me:
- Current phase and step
- What was last completed
- What's next to do
- Any blockers or notes from previous session

Do NOT start coding until I confirm your understanding is correct.

@phase-00-empty-shell.mdx
@boilerplate-definition.mdx

We're starting Phase 00: Empty Shell.

I've provided the phase spec and boilerplate definition.
Read them, then tell me:
1. What we're building in this phase
2. The steps involved
3. The gate (verification) for each step

Don't start coding until I approve your plan.

@phase-01-multi-tenant-auth.mdx
@patterns.mdx
@database-schema.mdx (if needed)

We're starting Phase 01: Multi-Tenant Auth.

I've provided the phase spec and patterns.
Read them, then tell me:
1. What auth system we're implementing
2. The database models involved
3. How multi-tenancy works
4. The steps and gates

Don't start coding until I approve your plan.

@phase-01.5-design-system.mdx
@18-design-system/index.mdx
@18-design-system/design-tokens.mdx
@18-design-system/components/index.mdx
@17-ui-screenshots/index.mdx

We're starting Phase 01.5: Design System.

I've provided the phase spec, design tokens, and UI screenshots.
Read them, then tell me:
1. The design system we're implementing (Apple-Screver Hybrid)
2. Key color tokens and typography
3. Component patterns to follow
4. How to validate against the screenshots

Don't start coding until I approve your plan.

@phase-02-employee-entity.mdx
@patterns.mdx
@service-patterns.mdx

We're starting Phase 02: Employee Entity.

I've provided the phase spec and code patterns.
Read them, then tell me:
1. The Employee model structure
2. CRUD operations needed
3. API endpoints to create
4. The exact patterns to follow

Don't start coding until I approve your plan.

@phase-03-org-structure.mdx
@patterns.mdx
@service-patterns.mdx
@domain-models.mdx (for flexible org model reference)

We're starting Phase 03: Org Structure.

I've provided the phase spec and domain models.
Read them, then tell me:
1. How the flexible org structure works
2. Manager relationships (primary, dotted-line, additional)
3. Team and department membership
4. The OrgService operations

Don't start coding until I approve your plan.

@phase-XX-[name].mdx
@patterns.mdx
@service-patterns.mdx
@[relevant-reference].mdx (if applicable)

We're starting Phase XX: [Name].

I've provided the phase spec and relevant patterns.
Read them, then tell me:
1. What we're building
2. Dependencies on previous phases
3. Database changes (if any)
4. API endpoints and frontend routes
5. Steps and gates

Don't start coding until I approve your plan.

CHECKPOINT: 
1. What step are we on?
2. Have you drifted from the plan?
3. What's your current progress?
4. Any blockers?

Update PROJECT_STATE.md with current status.

STOP. 

You're going off track. We're supposed to be doing [X], 
but you're doing [Y].

Re-read PROJECT_STATE.md and confirm what the current step is.
Do NOT continue until I approve.

Is this improvement in the current step's scope?

If NO: Do not make this change. Add it to a "future enhancements" 
note in PROJECT_STATE.md and continue with the current task.

If YES: Show me the specific step that requires this change.

You need more context. I'm providing [document name].
Read it, then tell me how it affects our current work.

We're ending this session.

Update PROJECT_STATE.md with:
1. Mark completed steps with ✅ and timestamp
2. Update "Current Step" to where we stopped
3. Write a "Handoff Note" describing:
   - What was just completed
   - What's next
   - Any blockers or issues
   - Files that need attention

Show me the updated content before committing.

# Review the changes
git diff PROJECT_STATE.md WHAT_EXISTS.md

# Commit (use conventional commit format!)
git add PROJECT_STATE.md WHAT_EXISTS.md
git commit -m "chore: update state after [brief description]"

<type>: <description>

# Features
git commit -m "feat: add employee dashboard"
git commit -m "feat: implement time-off request workflow"

# Bug fixes
git commit -m "fix: resolve login timeout issue"
git commit -m "fix: correct date format in reports"

# Documentation
git commit -m "docs: update API endpoint guide"
git commit -m "docs: add troubleshooting section"

# Refactoring
git commit -m "refactor: simplify auth middleware"
git commit -m "refactor: extract validation utilities"

# Breaking changes (add ! for major version bump)
git commit -m "feat!: redesign authentication API"

# These will FAIL:
git commit -m "update stuff"           # No type
git commit -m "Feature: add login"     # Wrong case (Feature vs feat)
git commit -m "feat add login"         # Missing colon
git commit -m "FEAT: add login"        # Uppercase
git commit -m "wip"                    # Not descriptive

STOP. That commit message doesn't follow conventional commits.

Correct format: <type>: <description>
Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Change to: "[correct message]"

We've completed Phase XX.

1. Update PROJECT_STATE.md - move phase to "Completed Phases"
2. Update WHAT_EXISTS.md with all new:
   - Database models
   - API endpoints
   - Frontend routes
   - Established patterns
3. Create git tag: git tag phase-XX-name
4. Show me both files before committing.

Read PROJECT_STATE.md and WHAT_EXISTS.md.
Tell me: current phase, current step, what's next.
Wait for my approval before coding.

Before editing this file, confirm:
1. Is it in the locked files list?
2. What pattern am I copying from?
3. What's the gate for this step?

CHECKPOINT: What step are we on? Any drift? Update PROJECT_STATE.md.

STOP. You're off track. Re-read PROJECT_STATE.md. 
Do NOT continue until I approve.

Ending session. Update PROJECT_STATE.md with completed steps, 
current position, and handoff note. Show me before commit.

Phase XX complete. Update both state files, create git tag, 
show me before commit.

You're not following the established pattern.

Look at [file path] for the correct pattern.
Your code should match EXACTLY:
- Same import structure
- Same class decorators
- Same method signatures
- Same error handling

Fix it before continuing.

STOP. Check if this already exists.

Search for: [component/service name]
Check WHAT_EXISTS.md for existing implementations.

If it exists, use the existing one. Do NOT create a duplicate.

STOP. New dependencies require approval.

Is [package name] in the locked tech stack?
Check: constraints.mdx or boilerplate-definition.mdx

If not listed, explain why it's needed and wait for approval.

Your context seems lost. Let's reset.

1. Read PROJECT_STATE.md
2. Read WHAT_EXISTS.md
3. Tell me what you understand about our current state
4. Wait for my confirmation before continuing

🛑 CHECKPOINT 1 - Code Ready

I've completed:
- Created branch: feature/[name]
- Made code changes
- Committed: "[message]"

**Please verify:** Review the code diff above.

**When ready:** Reply "OK to push" to continue.

🛑 CHECKPOINT 2 - Preview Ready

Preview URL: https://hrms-docs-pr-N-xxx.run.app

**Please verify:** Open the preview and check the feature works.

**When ready:** Reply "OK to merge" to continue.

🛑 CHECKPOINT 3 - Staging Ready

Staging URL: https://hrms-docs-staging-xxx.run.app

**Please verify:** Test in staging environment.

**When ready:** Reply "OK to deploy" to deploy to production.

🛑 CHECKPOINT 4 - Production Live

Production URL: https://docs.hrms.bluewoo.com

**Please verify:** Confirm feature is live in production.

**When ready:** Reply "Complete" to finish.