Development Workflow

This workflow ensures consistent, predictable development with AI assistants.

Pre-Session Setup

0. Session Start Ritual (MANDATORY)

Step 1: Read State Files (2 minutes)

cat PROJECT_STATE.md   # Current phase, step, locked files
cat WHAT_EXISTS.md     # Patterns to copy, what's built

Step 2: Check Git Status (30 seconds)

git status
git log -3 --oneline

Step 3: State Understanding (MANDATORY)

Write this exact template:

> "I've read the state files. Here's my understanding:
> - Current Phase: [X]
> - Current Step: [Y of Z]
> - Last Completed: [description]
> - I will now work on: [description]
> - The gate for this step is: [gate criteria]
> - Pattern I'll copy from: [file path]
> - Files I expect to modify: [list]
>
> Is this correct? Should I proceed?"

Step 4: WAIT for Explicit Approval

Do NOT proceed until user confirms.

1. Plan Before Coding (CRITICAL)

Before ANY implementation:

1. Explore: Read relevant files, understand current state
2. Plan: Propose a plan and WAIT for approval
3. Confirm: State understanding: "I will [X]. Gate is [Y]. Proceed?"
4. Only then: Start implementation

AI agents tend to jump straight to coding. This step prevents runaway implementations.

2. Check Current State

• Read PROJECT_STATE.md for current phase and step
• Read WHAT_EXISTS.md for patterns and inventory
• Check git status for uncommitted changes
• Review recent commits

3. Load Context

• Read current phase specification
• Read Patterns for code patterns
• Read Constraints for hard rules
• Check what files are locked

4. Prepare AI Prompt

Include in every prompt:

• Current phase number and name
• What's already complete
• What needs to be built next
• Relevant patterns
• Constraints that apply

Session Workflow

Step 1: Understand Task

• Read phase specification
• Identify dependencies (must be complete)
• Identify deliverables
• Check completion criteria

Confirm Understanding: Before writing any code, state:

"I understand I need to [specific task]. The verification gate is [specific check]. Should I proceed?"

Wait for explicit approval before implementing.

Step 2: Check Constraints

• Verify technology versions
• Check for forbidden patterns
• Verify complexity limits
• Check locked files

Step 3: Follow Pattern

• Use exact pattern from Patterns
• No variations or "improvements"
• Copy structure from similar code
• Follow naming conventions

Step 4: Implement

• Build one piece at a time
• Test after each piece
• Commit frequently
• Document decisions

Step 5: Verify

• Check against completion criteria
• Run tests
• Verify constraints not violated
• Check pattern adherence

Step 6: Document

• Update context with progress
• Document any new patterns
• Update phase status
• Commit changes

Escape Hatch Rule

If unsure about ANY aspect of a task:

1. STOP - Do not guess or assume
2. ASK - State what you're unsure about
3. PROPOSE - Offer 2-3 options if applicable
4. WAIT - Do not proceed until clarified

Examples of when to use escape hatch:

• Unclear which pattern to use
• Task seems to conflict with constraints
• Multiple valid approaches exist
• Scope seems larger than expected
• File modification affects locked files

"When in doubt, ask. A 30-second clarification prevents 30-minute mistakes."

Gate System

Every phase has 5 gates. Complete all gates before moving on.

GATE 1: BUILD

• Implement feature following patterns
• Follow constraints strictly
• No shortcuts or hacks

GATE 2: TEST

• Write unit tests
• Write integration tests
• Manual testing
• All tests passing

GATE 3: REVIEW & APPROVE

• Self-review code
• Architecture review
• Run audit check: "Are there redundant methods, dead code, duplication, or over-engineering? Is the implementation minimal and focused?"
• Document approval reasoning
• Mark as APPROVED

GATE 4: DOCUMENT

• Update architecture docs
• Update API docs
• Create ADR if needed
• Update context files

GATE 5: COMMIT & TAG

• Git commit with clear message
• Tag: phase-XX-name (e.g., phase-01-multi-tenant-auth)
• Push to main
• Update status tracker

Git Branching & Deployment Integration

Branch Workflow for AI Sessions

At Session Start:

git checkout main
git pull origin main
git checkout -b feature/phase-XX-step-YY

During Session:

# Commit frequently with conventional commits
git add .
git commit -m "feat: implement step YY - [description]"
git push origin feature/phase-XX-step-YY

Conventional Commits (REQUIRED)

Format: <type>: <description>

Breaking Changes: Add ! after type for major version bump:

feat!: redesign API endpoints

Examples:

# Good
git commit -m "feat: add employee dashboard"
git commit -m "fix: resolve login timeout"
git commit -m "docs: update API guide"

# Bad (will be rejected)
git commit -m "update stuff"
git commit -m "Feature: add login"

Versions are auto-bumped on merge to main via semantic-release.

At Session End:

# Create PR
gh pr create --title "feat: phase XX step YY" --body "Implements [description]"

Environment Flow

Feature Branch → PR (Preview) → Merge → Staging → Production

Deploying to Production

After verifying staging:

gh workflow run deploy.yml -f deploy_production=true

See Development Workflow for complete deployment guide.

Mandatory Deployment Checkpoints (ENFORCED)

The 4-Checkpoint System

Every deployment follows this exact flow with mandatory human approval at each gate:

┌─────────────────────────────────────────────────────────────────────────┐
│  PHASE A: Code Changes                                                  │
│  ├── Create feature branch                                              │
│  ├── Make code changes                                                  │
│  ├── Commit changes                                                     │
│  └── 🛑 CHECKPOINT 1: "Code ready. OK to push?"                        │
│       └── WAIT for human: "OK to push"                                  │
├─────────────────────────────────────────────────────────────────────────┤
│  PHASE B: Pull Request                                                  │
│  ├── Push to GitHub                                                     │
│  ├── Create PR                                                          │
│  ├── Wait for preview deployment (~5 min)                               │
│  └── 🛑 CHECKPOINT 2: "Preview at [URL]. OK to merge?"                 │
│       └── WAIT for human: "OK to merge"                                 │
├─────────────────────────────────────────────────────────────────────────┤
│  PHASE C: Staging                                                       │
│  ├── Merge PR to main                                                   │
│  ├── Wait for staging deployment (~5 min)                               │
│  └── 🛑 CHECKPOINT 3: "Staging at [URL]. OK to deploy production?"     │
│       └── WAIT for human: "OK to deploy"                                │
├─────────────────────────────────────────────────────────────────────────┤
│  PHASE D: Production                                                    │
│  ├── Trigger production deployment                                      │
│  ├── Wait for deployment (~2 min)                                       │
│  └── 🛑 CHECKPOINT 4: "Production live at [URL]. Confirm complete."    │
│       └── WAIT for human: "Complete"                                    │
└─────────────────────────────────────────────────────────────────────────┘

Checkpoint Response Table

Checkpoint Protocol for AI Agents

At each checkpoint, AI MUST:

1. STOP all execution
2. SHOW the relevant information (diff, URL, status)
3. ASK for explicit confirmation using the exact phrase
4. WAIT - Do NOT proceed until human responds
5. VERIFY response matches expected format before continuing

Example Checkpoint 2 Output:

---

## ✅ CHECKPOINT 2 - Phase B Complete

I have completed:
1. ✅ Pushed branch to GitHub
2. ✅ Created PR #N: [URL]
3. ✅ Preview deployed successfully

### Preview URL:
**https://hrms-docs-pr-N-xxxx.run.app**

---

## 🛑 WAITING FOR YOUR CONFIRMATION

**Please verify:** 
1. Open the preview URL above
2. Check that the feature works correctly
3. Verify no visual/functional regressions

**When ready, reply:** `"OK to merge"` to proceed to Phase C

Why Checkpoints Are Mandatory

GitHub Enforcement

Branch protection is configured with:

• ✅ PRs required - No direct pushes to main
• ✅ Tests required - CI must pass before merge
• ✅ Enforce for admins - Even admins cannot bypass
• ❌ Force pushes disabled - History is protected
• ❌ Deletions disabled - Branch cannot be deleted

Session End Ritual (MANDATORY)

Step 1: Update PROJECT_STATE.md

• Mark completed steps with ✅ and timestamp
• Update "Current Step" section
• Update progress percentage
• Add any new locked files
• Document blockers (if any)

Step 2: Run Final Verification

git status
npm test  # or applicable test command

Step 3: Write Handoff Note

Add to PROJECT_STATE.md under "What I'm About To Do":

• Exact next action
• Any blockers encountered
• Files that need attention
• Context next session needs

Step 4: Create PR and Commit State Files

# Push feature branch
git push origin feature/phase-XX-step-YY

# Create PR (triggers preview deployment)
gh pr create --title "feat: phase XX step YY"

# If step complete and approved, merge
gh pr merge --squash

30-Minute Checkpoint System

Set a timer. Every 30 minutes, STOP and verify:

Checkpoint Questions

1. Am I still working on the documented current step?
2. Have I drifted into "improvements" or "refactoring"?
3. Is my code following the exact pattern from WHAT_EXISTS.md?
4. Have I updated PROJECT_STATE.md recently?
5. Am I blocked? Should I ask for help?

If Any Answer Is Concerning

1. Stop current work
2. Update PROJECT_STATE.md with current status
3. Ask for clarification before continuing

Error Recovery Protocol

When something breaks or goes wrong:

Step 1: STOP IMMEDIATELY

Do not try to "fix" the issue by making more changes.

Step 2: Document the Error

Add to PROJECT_STATE.md:

### ERROR ENCOUNTERED
- **Time:** HH:MM
- **Step:** XX
- **Error:** [describe what happened]
- **Files Modified Before Error:** [list]
- **Last Known Good State:** [commit hash or description]

Step 3: Assess Rollback Need

git status
git diff

Step 4: Rollback Options

Step 5: Resume Protocol

After recovery, restart Session Start Ritual from Step 0.

Development Phases

Phase 1: Foundation

[ ] Prisma schema with flexible org structure
[ ] Junction tables for all many-to-many
[ ] RLS policies
[ ] Auth.js with Google SSO
[ ] Tenant context middleware
[ ] Dashboard shell

Phase 2: Org Structure

[ ] Org service with all operations
[ ] API endpoints for org management
[ ] Org chart visualization (React Flow)
[ ] Employee org summary card
[ ] Manager assignment UI
[ ] Team/department/role management

Phase 3: Core Modules

[ ] Time-off policies & requests
[ ] Approval workflow (any manager can approve)
[ ] Document upload & management
[ ] Goals/OKR

Phase 4: AI Integration

[ ] RAG for policy Q&A
[ ] AI.org.explain()
[ ] AI.org.validate()
[ ] AI.org.generateStructure()
[ ] Chat widget

Success Criteria

Functional

• All org structure operations working
• Multi-manager, multi-team, multi-role all functional
• Time-off with flexible approval
• AI org tools operational

Performance

• Under 200ms API response (p95)
• Org chart renders 500+ nodes

Reliability

• 99.9% uptime over 30 days
• No data leakage between tenants

Testing

• 70% coverage on critical paths

• Org structure edge cases covered

Documentation

• OpenAPI spec complete
• Developer onboarding under 1 day

AI Prompt Template

Use this template for every AI interaction:

Continue Phase XX: [Name]

Context:
- Current phase: XX of 09
- Completed phases: [list completed]
- Current task: [specific task]

Patterns:
- [relevant patterns]

Constraints:
- [relevant constraints]

Task:
[Specific task to implement]

Rules:
- Follow exact patterns (no variations)
- Respect all constraints
- Don't touch locked files
- Complete current task only

Common Workflows

Starting New Phase

1. Verify dependencies complete
2. Read phase specification
3. Load relevant patterns
4. Start with GATE 1: BUILD

Continuing Phase

1. Check context for current status
2. Read what's already built
3. Continue from where left off
4. Follow gate system

Fixing Issues

1. Identify issue
2. Check if violates constraints
3. Fix following patterns
4. Test fix
5. Update context

Anti-Patterns

DON'T:

• Start new phase before current complete
• Suggest "better" patterns
• Add features not in specification
• Touch locked files
• Violate constraints
• Skip gates
• Work on multiple phases
• Proceed without confirming understanding
• Guess when requirements are unclear
• Add "helpful" features not requested
• Install dependencies without approval
• Modify files outside current task scope

DO:

• Complete one phase fully
• Follow established patterns
• Stay within specification
• Respect all constraints
• Complete all gates
• Focus on current task