---
description: "AI Workflow Engine - State-Specific Behavior Rules"
globs: "**/*"
alwaysApply: true
priority: 1
version: 3.0.0
tags: [workflow, states, behavior, mandatory]
lastUpdated: 2025-11-28
---

# 🔄 WORKFLOW STATES - BEHAVIOR ENFORCEMENT

⚠️  **CRITICAL:** State-based behavior (alwaysApply: true)

## 📊 SIX WORKFLOW STATES

After getting state via command or reading STATUS.txt, apply corresponding behavior:

### 🔵 UNDERSTANDING State
```
Meaning: Requirements being analyzed, no design yet

Your Behavior:
  ✅ Ask clarifying questions
  ✅ Understand requirements fully
  ✅ Identify ambiguities
  ✅ Review architecture documentation
  ✅ Read existing code to understand context
  
  ❌ DON'T start coding yet
  ❌ DON'T make assumptions
  ❌ DON'T suggest commits

When to progress: User confirms understanding complete
Progress command: npx ai-workflow sync --state DESIGNING --json --silent
```

### 🟢 DESIGNING State
```
Meaning: Design approved, ready to implement

Your Behavior:
  ✅ Design architecture
  ✅ Plan implementation approach
  ✅ Identify files to create/modify
  ✅ Review logic flow documentation
  ✅ Consider alternatives
  
  ❌ DON'T write code yet
  ❌ DON'T change architecture without discussion
  ❌ DON'T suggest commits yet (no tests!)

When to progress: Design approved by user
Progress command: npx ai-workflow sync --state IMPLEMENTING --json --silent
```

### 🟡 IMPLEMENTING State
```
Meaning: Write production code

Your Behavior:
  ✅ Write production code
  ✅ Implement according to design
  ✅ Create planned files
  ✅ Follow coding standards
  ✅ Add requirement tags (@requirement)
  
  ❌ DON'T write tests yet (separate phase)
  ❌ DON'T suggest commits (no tests!)
  ❌ DON'T skip requirement tags

When to progress: Implementation complete
Progress command: npx ai-workflow sync --state TESTING --json --silent
```

### 🟠 TESTING State
```
Meaning: Write comprehensive tests

Your Behavior:
  ✅ Write comprehensive unit tests
  ✅ Write integration tests if needed
  ✅ Test edge cases
  ✅ Ensure coverage >70%
  ✅ Run tests and verify they pass
  
  ❌ DON'T skip tests (MANDATORY!)
  ❌ DON'T suggest commits without tests
  ❌ DON'T say "tests can be added later"

When to progress: All tests written and passing
Progress command: npx ai-workflow sync --state REVIEWING --json --silent
```

### 🔴 REVIEWING State
```
Meaning: Review code quality

Your Behavior:
  ✅ Review code for quality
  ✅ Check requirements all satisfied
  ✅ Look for potential improvements
  ✅ Verify test coverage adequate
  ✅ Run: npx ai-workflow validate --json --silent
  
  ❌ DON'T skip review
  ❌ DON'T suggest commits yet
  ❌ DON'T skip validation

When to progress: Review complete, validation passes
Progress command: Auto-progress to READY_TO_COMMIT if validation passes
```

### 🟣 READY_TO_COMMIT State
```
Meaning: Validation passed, safe to commit

Your Behavior:
  ✅ Suggest commit with good message
  ✅ Include task reference
  ✅ Remind to complete task after
  ✅ Verify all quality gates passed
  
  ❌ DON'T suggest --no-verify
  ❌ DON'T bypass quality gates

After commit: Remind user to run npx ai-workflow task complete
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 🚫 CRITICAL: State-Based Restrictions

**NEVER suggest commits unless state is READY_TO_COMMIT:**

```
If state is UNDERSTANDING:
  Response: "We're still in UNDERSTANDING state. Let's finalize requirements first."

If state is DESIGNING:
  Response: "Design is ready but no code yet. Let me implement first."

If state is IMPLEMENTING:
  Response: "Code is ready but needs tests. Let me add tests first."

If state is TESTING:
  Response: "Tests pass but needs review. Let me review quality first."

If state is REVIEWING:
  Response: "Review done. Let me run validation: npx ai-workflow validate --json --silent"

Only if state is READY_TO_COMMIT:
  Response: "✓ Validation passed! Safe to commit: git commit -m 'feat: ...'"
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 📖 DETAILED STATE RULES

**For detailed rules per state, read:**

- `.cursor/rules/state-behaviors/UNDERSTANDING.md` - Understanding state rules
- `.cursor/rules/state-behaviors/DESIGNING.md` - Designing state rules
- `.cursor/rules/state-behaviors/IMPLEMENTING.md` - Implementing state rules
- `.cursor/rules/state-behaviors/TESTING.md` - Testing state rules
- `.cursor/rules/state-behaviors/REVIEWING.md` - Reviewing state rules
- `.cursor/rules/state-behaviors/READY_TO_COMMIT.md` - Ready to commit state rules

**Each file contains:**
- Full list of allowed actions
- Full list of forbidden actions
- Detailed progression protocol
- Examples and best practices
- Self-check guidelines

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**This rule uses alwaysApply: true**  
**State-based behavior is MANDATORY**  
**Prevents premature commits and skipped quality gates**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Priority:** 1 (Read after 000-workflow-core.mdc)  
**Version:** 3.0.0  
**Purpose:** Enforce state-specific behavior rules  
**Maintenance:** Update template, then run: `npx ai-workflow migrate --update-mdc-files`