010-workflow.mdc

---
title: Development Workflow & Context Management
description: Plan/Implement/Review workflow with context persistence for complex projects.
alwaysApply: true
priority: 10
---

#  GOLDEN RULES (READ FIRST)

**YOU MUST FOLLOW THIS THREE-PHASE APPROACH FOR ALL NON-TRIVIAL WORK:**

> [!NOTE]
> **HITL (human-in-the-loop)**: Any step that requires **explicit user approval** is a HITL gate. Do not proceed past a HITL gate until approval is received.

1. **PLAN** -> Design solution -> Document approach -> **WAIT FOR EXPLICIT APPROVAL (HITL)**
2. **IMPLEMENT** -> Code ONLY what was approved -> **STOP** when agreed scope is complete
3. **REVIEW** -> Verify results -> Suggest improvements -> Return to PLAN phase

**AGENT AUDIT REQUIREMENTS (ADDITIONAL):**
- Follow [020-agent-audit.mdc](020-agent-audit.mdc) for **explicit authorization of remote mutations**, **risk-based checkpoints**, **local verification**, and **proportional audit reporting**.

** CRITICAL VIOLATIONS TO AVOID:**

```diff
 DON'T DO THIS:
User: "Can you add authentication?"
AI: [Immediately starts coding without discussion]

 DO THIS INSTEAD:
User: "Can you add authentication?"
AI: "Let me design a solution first. Key decisions needed:
     - OAuth 2.0 vs local authentication?
     - JWT tokens vs session-based?
     - User data storage location?
     - Password hashing strategy?

     Let's agree on the approach before I write any code."
```

**WHY THIS MATTERS:**
-  Skipping planning -> Wasted time, wrong solutions, scope creep
-  Implementing unplanned features -> Breaking existing code, technical debt
-  Not stopping after agreed scope -> Confusion, frustration, rework

---

# Development Workflow & Context Management

**Role:** Workflow orchestrator that combines structured development phases with persistent context management.

**Integration:** This rule works alongside your detailed coding standards (`100-core.mdc` and language-specific rules) and provides workflow structure for complex tasks.

---

##  Just-in-Time Rule Loading

**DON'T READ ALL 35 RULES AT ONCE!** Load rules as needed:

| Working on... | Read these rules |
|--------------|------------------|
| **Python code** | `200-python.mdc` |
| **AWS infrastructure** | `410-aws.mdc` |
| **Terraform modules** | `180-terraform.mdc` |
| **Documentation** | `810-documentation.mdc`, `800-markdown.mdc` |
| **Creating PR** | `130-git.mdc` |
| **GitHub Actions** | `160-github-actions.mdc` |
| **Security review** | `310-security.mdc` |

**This prevents information overload and keeps you focused.**

---

##  Core Workflow: Plan / Implement / Review

You MUST follow this three-phase approach for all non-trivial changes:

### Phase 1: Planning

 **CRITICAL:** You MUST NOT begin implementation until:
- [ ] User has explicitly approved the plan
- [ ] All clarifying questions have been answered
- [ ] The scope is clearly defined and agreed upon
- [ ] Risks and dependencies are identified

### PRD-first development (North Star)

For non-trivial work, keep a single “north star” scope document and use it to drive small, sequential feature slices.

- **Recommended file**: `tmp/prd.md`
- **Design doc (recommended when architecture/approach matters)**: `tmp/design.md`
- **Greenfield**: Define scope, non-goals, key flows, architecture, milestones
- **Brownfield**: Capture current state + next desired state + constraints
- **Rule**: Break work into features small enough for the agent to execute reliably (one feature per cycle)

**When to create `tmp/design.md`:**
- Level 3-4 tasks (multi-module or architectural)
- Any time there are multiple valid approaches with meaningful tradeoffs
- Any time interfaces, data models, or operational behaviors might change

**When Planning is Required:**
- Multiple files or modules affected
- New features or significant refactoring
- Complex integrations
- Security-sensitive changes
- Architectural decisions needed

**Process:**
1. **Analyze the request** - Understand scope, constraints, and requirements
2. **Check existing code** - Look for patterns, conventions, and reusable components
3. **Design the solution** - Propose approach with alternatives considered
4. **Create/update context files** - Document plan in `tasks.md` or `active-context.md` (in `tmp/` directory)
5. **WAIT FOR APPROVAL** - Present plan and await explicit confirmation before proceeding

**Output:**
- Clear problem statement
- Proposed solution with rationale
- Alternative approaches considered (with pros/cons)
- Files/modules affected
- Dependencies and risks
- Testing strategy
- Updated `tasks.md` with plan

**Key Questions to Answer:**
- What is the simplest solution that meets requirements?
- Can we reuse existing code or patterns?
- What are the security implications?
- How will this be tested?
- What documentation needs updating?

**VIOLATION WARNING:** Proceeding without approval wastes time and creates frustration.

---

### Phase 2: QA Validation  (Level 2+ Tasks)

**When:** Before Implementation phase for Level 2+ tasks. Can be called explicitly with "QA" command.

**Purpose:** Technical validation to prevent implementation failures.

**Process:**
1. **Dependency Verification** - Check all required packages/tools are installed and compatible
2. **Configuration Validation** - Verify config files are valid and platform-compatible
3. **Environment Validation** - Ensure build tools available and permissions sufficient
4. **Minimal Build Test** - Test core functionality works

**QA Validation Checklist:**
- [ ] All dependencies installed and compatible
- [ ] Configuration files valid and platform-compatible
- [ ] Build environment ready
- [ ] Minimal build test passes

**If QA fails:**
- Document issues clearly
- Provide remediation steps
- Block implementation until resolved
- Re-run QA after fixes

**Output:**
- QA validation report (pass/fail)
- Issues found (if any)
- Remediation steps (if needed)
- Clear to proceed to Implementation (if pass)

---

### Phase 3: Implementation

 **IMPLEMENTATION GATE CHECKS:**

**You MUST NOT start implementation until:**
- [ ] Explicit user approval received in Planning phase
- [ ] QA Validation passed (for Level 2+ tasks)
- [ ] Creative Phase completed (for Level 4 tasks)
- [ ] All questions answered and scope agreed

**Process:**
1. **Follow the agreed plan** - Implement exactly what was discussed
2. **Make incremental changes** - Small, testable commits
3. **Update context files** - Track progress in `progress.md` or `tasks.md`
4. **Stop at boundaries** - Don't fix unrelated issues or add unplanned features
5. **Complete the agreed scope** - Then STOP and wait for review

### Context reset between Plan → Build

When moving from planning to implementation, prefer a fresh context window so the agent has maximum room to reason.

- **Rule**: After the plan is approved, restart the chat/session before coding
- **Input**: Provide the approved plan doc (and only the minimum extra context needed)
- **Goal**: Keep implementation context lightweight; avoid carrying long planning threads into execution

**Constraints:**
-  Implement only what was planned
-  Follow all coding standards from `100-core.mdc` and language-specific rules
-  Include error handling, logging, and security considerations
-  Don't refactor unrelated code
-  Don't add features not in the plan
-  Don't optimize prematurely

**If you encounter issues:**
- Trivial fixes (typos, obvious bugs): OK to fix immediately
- Substantial changes needed: STOP, document in Review phase, discuss in next Planning phase

** Common Implementation Violations:**

```diff
 BAD: Adding unplanned features
User: "Add a login form"
AI: [Adds login form + password reset + 2FA + OAuth integration]

 GOOD: Implementing only what was agreed
User: "Add a login form"
AI: [Adds only login form as specified]
     "Login form complete. For next phase, we could discuss:
      - Password reset flow?
      - 2FA integration?
      - OAuth providers?"
```

---

### Phase 4: Review

**When:** After implementation is complete.

**Process:**
1. **Review implemented changes** - Verify they match the plan
2. **Check for issues** - Security, bugs, edge cases, performance
3. **Suggest improvements** - But DON'T implement them yet
4. **Update context files** - Document findings in `reflect-*.md` or `tasks.md`
5. **Identify cleanup opportunities** - Can we remove/simplify existing code?
6. **Propose next steps** - What should happen next?

### System evolution (make the agent better over time)

Treat recurring mistakes as a signal to improve the system, not just the code:

- **If a bug recurs**: update the relevant rule(s), command(s), or reference docs so it doesn’t happen again
- **If validation was missed**: update templates/commands to force the check (tests, lint, security scan)
- **Capture learnings**: record patterns in `tmp/reflect-*.md` (Level 3-4) and keep the guidance crisp

**Review Checklist:**
- [ ] Changes match the agreed plan
- [ ] Security considerations addressed
- [ ] Error handling appropriate
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No unrelated changes
- [ ] Code follows all standards from `100-core.mdc`

**Output:**
- Summary of what was implemented
- Issues found (if any)
- Suggestions for improvements (to be discussed in next Planning phase)
- Updated context files

---

##  Context File Management

**IMPORTANT**: Context files are **workspace-specific** and should be in the **tmp/** directory in the project root, NOT in the rules directory. This allows each workspace to have its own context while sharing rules via symlinks.

> [!IMPORTANT]
> `tmp/` is intended for **workspace-local context and artifacts** and should be **gitignored by default**.
>
> Do **not** commit or push files under `tmp/` unless the user explicitly requests it (for example, promoting a draft document from `tmp/` into the repo proper).

> [!NOTE]
> For prompt packing, retrieval, and “frequent intentional compaction” patterns, see `015-context-engineering.mdc`.

**Templates:** Copy/paste-ready templates live alongside these rules under `templates/` (e.g., `.cursor/rules/templates/` when installed). In this repo, that path is `rules/templates/`. Copy them into `tmp/` when you start a new workspace.

For complex projects, maintain context files in the `tmp/` directory:

### `project-brief.md` - Project Overview (Optional, Recommended)
Use this when starting work in a new repo/workspace (or when context resets) so the agent has stable, high-level grounding.
- **Template:** `templates/project-brief.md.template`
- **Workspace file:** `tmp/project-brief.md`

### `tasks.md` - Source of Truth
- **Template:** `templates/tasks.md.template`
- **Workspace file:** `tmp/tasks.md`

### `active-context.md` - Current Focus
- **Template:** `templates/active-context.md.template`
- **Workspace file:** `tmp/active-context.md`

### `progress.md` - Implementation Status
- **Template:** `templates/progress.md.template`
- **Workspace file:** `tmp/progress.md`

### `reflect-*.md` - Review Documents
Create one per significant task:
- **Template:** `templates/reflect-template.md.template`
- **Workspace file:** `tmp/reflect-<task>.md`

---

##  Complexity Levels

Adapt workflow based on task complexity:

### Level 1: Simple (Quick Fixes)
- **Workflow:** Direct implementation -> Quick review
- **Context Files:** Optional
- **Example:** Fix typo, update comment, simple bug fix
- **Skip Planning:** Yes, for obvious fixes

### Level 2: Moderate (Single Feature)
- **Workflow:** Brief plan -> QA Validation -> Implement -> Review
- **Context Files:** `tasks.md` recommended
- **Example:** Add new function, update single module
- **Skip Planning:** No

### Level 3: Complex (Multi-Module)
- **Workflow:** Full Plan -> Creative Phase -> QA Validation -> Implement -> Review -> Archive
- **Context Files:** `tasks.md`, `active-context.md`, `progress.md`
- **Example:** New feature spanning multiple files, API changes
- **Skip Planning:** Never

### Level 4: Very Complex (Architectural)
- **Workflow:** Detailed Plan -> Creative Phase (MANDATORY) -> QA Validation -> Implement -> Review -> Archive
- **Context Files:** All files, including `creative-*.md` for design decisions
- **Example:** Major refactoring, new subsystem, architectural changes
- **Skip Planning:** Never

---

##  Workflow Integration

### For Simple Tasks (Level 1)
```
User Request -> Quick Implementation -> Brief Review -> Done
```

### For Moderate Tasks (Level 2)
```
User Request -> Brief Planning (WAIT) -> QA Validation -> Implementation -> Review -> Done
```

### For Complex Tasks (Level 3-4)
```
User Request -> Planning Phase (WAIT) -> Creative Phase (MANDATORY) -> QA Validation -> Implementation Phase -> Review Phase -> Archive
```

---

##  Creative Phase (Level 3-4 Tasks)

** ENFORCEMENT:** Creative Phase is **MANDATORY** for Level 3-4 tasks before Implementation.

**When Required:**
- Level 3: Complex multi-module features requiring design decisions
- Level 4: Architectural changes, multiple valid approaches exist
- Design decisions affect multiple components

** IMPLEMENTATION BLOCK:**
If Creative Phase is required but not completed:
```
 IMPLEMENTATION BLOCKED
Creative phases MUST be completed before implementation.

Required Creative Phases:
- [ ] [Creative Phase 1]
- [ ] [Creative Phase 2]

 This is a HARD BLOCK
Implementation CANNOT proceed until all creative phases are completed.
```

**Process:**
1. **Entry Gate Verification:**
   - [ ] Task complexity is Level 3-4
   - [ ] Design decisions identified
   - [ ] Creative phase requirements documented

2. **Design Exploration:**
   - Identify design options (2-4 alternatives)
   - Compare pros/cons in tabular format
   - Analyze against requirements and constraints
   - Document decision rationale

3. **Exit Gate Verification:**
   - [ ] All decisions documented
   - [ ] Rationale provided for choices
   - [ ] Implementation plan outlined
   - [ ] Verification against requirements

4. **Documentation:**
   - Create `creative-*.md` with chosen approach
   - Update `tasks.md` with design decisions
   - Mark creative phase complete

5. **Proceed to QA Validation** (Level 2+) then Implementation

**Template:**
- **Template:** `templates/creative-template.md.template`
- **Workspace file:** `tmp/creative-<component-or-feature>.md`

---

##  QA Validation System (Detailed)

**Purpose:** Technical validation to prevent implementation failures due to missing dependencies, configuration issues, or environment problems.

**When:**
- **Mandatory** before Implementation for Level 2+ tasks
- Can be called explicitly with **"QA"** command (interrupts any process)
- After Creative Phase completion (Level 3-4)

**Four-Point Validation Process:**

### 1⃣ Dependency Verification

**Check:**
- All required packages/tools installed
- Versions compatible with requirements
- No missing dependencies

**Process:**
```bash
# Example checks:
- Check package.json / requirements.txt / pyproject.toml
- Verify Node.js/Python/other runtime versions
- Check if dependencies are installed (npm list, pip list, etc.)
- Verify version compatibility
```

**Output:**
- List of required dependencies
- List of installed dependencies
- Compatibility status
- Missing or incompatible dependencies (if any)

### 2⃣ Configuration Validation

**Check:**
- Configuration files exist and are valid
- Syntax is correct (JSON, YAML, TOML, etc.)
- Platform compatibility (Windows/macOS/Linux)
- Required settings present

**Process:**
```bash
# Example checks:
- Validate JSON/YAML/TOML syntax
- Check for required configuration keys
- Verify platform-specific settings
- Test configuration loading
```

**Output:**
- Configuration files checked
- Syntax validation status
- Platform compatibility status
- Missing or invalid configurations (if any)

### 3⃣ Environment Validation

**Check:**
- Build tools available (npm, pip, make, etc.)
- Permissions sufficient (write access, port availability)
- Environment variables set (if needed)
- Required ports available

**Process:**
```bash
# Example checks:
- Verify build tools installed (node, python, git, etc.)
- Check write permissions in project directory
- Verify port availability (if needed)
- Check environment variables
```

**Output:**
- Build tools status
- Permission status
- Environment readiness
- Missing tools or permission issues (if any)

### 4⃣ Minimal Build Test

**Check:**
- Build process works
- Core functionality testable
- No blocking errors

**Process:**
```bash
# Example checks:
- Run minimal build/test command
- Verify core functionality
- Check for blocking errors
- Test basic operations
```

**Output:**
- Build process status
- Functionality test status
- Errors found (if any)

### QA Validation Report Format

**Success Report:**
```
  QA VALIDATION STATUS
  Dependencies        All required packages installed
  Configurations      Format verified for platform
  Environment         Suitable for implementation
  Build Test          Core functionality verified

 VERIFIED - Clear to proceed to Implementation phase
```

**Failure Report:**
```
 QA VALIDATION FAILED

The following issues must be resolved before proceeding:

1⃣ DEPENDENCY ISSUES:
- [Detailed description]
- [Recommended fix]

2⃣ CONFIGURATION ISSUES:
- [Detailed description]
- [Recommended fix]

3⃣ ENVIRONMENT ISSUES:
- [Detailed description]
- [Recommended fix]

4⃣ BUILD TEST ISSUES:
- [Detailed description]
- [Recommended fix]

 IMPLEMENTATION BLOCKED until these issues are resolved.
Type 'QA' after fixing issues to re-validate.
```

### QA Command Precedence

**When user types "QA":**
1. **Immediate precedence** - Interrupts any current process
2. **Load QA process** - Execute four-point validation
3. **Remediation priority** - Fixes take priority over pending tasks
4. **Resume flow** - After PASS, resume previous process flow

**QA Override Message:**
```
 QA OVERRIDE ACTIVATED
All other processes paused
QA validation checks now running...
Any issues found MUST be remediated before continuing
```

### Common QA Fixes

**Dependency Issues:**
- Missing packages: Install with `npm install`, `pip install`, etc.
- Version conflicts: Update or downgrade packages
- Missing runtime: Install Node.js, Python, etc.

**Configuration Issues:**
- Invalid JSON/YAML: Fix syntax errors
- Missing keys: Add required configuration
- Platform incompatibility: Adapt for current OS

**Environment Issues:**
- Missing tools: Install required build tools
- Permission denied: Fix file/directory permissions
- Port in use: Kill process or change port

**Build Test Issues:**
- Build fails: Check error messages and fix
- Test fails: Verify minimal configuration
- Path issues: Use correct path separators for platform

---

##  Platform Awareness

**Automatic Platform Detection:**
- Detect operating system (Windows/macOS/Linux)
- Identify path separator format (`\` vs `/`)
- Detect shell environment (PowerShell/Bash/Zsh/Cmd)
- Adapt commands accordingly

**Platform Detection Process:**
1. Detect OS environment
2. Identify path separator format
3. Detect shell type
4. Adapt commands for platform

**Command Adaptation:**
- **Windows:** Use `dir`, `type`, backslash paths (`\`)
- **macOS/Linux:** Use `ls`, `cat`, forward slash paths (`/`)
- **PowerShell:** Use PowerShell-specific syntax
- **Bash/Zsh:** Use Unix-style commands

**Example:**
```bash
# Platform detection results
Operating System: macOS
Path Separator: /
Shell Environment: zsh
Command Adaptation: Required

# Commands automatically adapted:
# Windows: dir, type file.txt
# macOS/Linux: ls, cat file.txt
```

**When to Use:**
- Always detect platform before executing commands
- Adapt file paths for current OS
- Use platform-appropriate command syntax
- Verify platform compatibility for config files

---

##  Quick Start Commands

Users can trigger phases explicitly:

- **"Plan this:"** -> Enter Planning phase
- **"QA"** -> Run QA Validation (can interrupt any process)
- **"Implement:"** -> Enter Implementation phase (requires plan + QA pass for Level 2+)
- **"Review:"** -> Enter Review phase
- **"What's the status?"** -> Check context files and current phase

---

##  Integration with Other Rules

This workflow rule integrates with:

- **`100-core.mdc`**: Coding standards apply during Implementation
- **Language-specific rules** (`200-python.mdc`, etc.): Language patterns apply during Implementation
- **`130-git.mdc`**: Commit standards apply when creating commits
- **`160-github-actions.mdc`**: CI/CD considerations during Planning

---

##  Best Practices

1. **Always check context files** before starting work
2. **Update context files** as you progress
3. **Don't skip phases** for complex tasks
4. **Preserve context** between sessions using files
5. **Be explicit** about which phase you're in
6. **Wait for approval** before moving from Planning to Implementation
7. **Run QA Validation** before Implementation for Level 2+ tasks
8. **Complete Creative Phase** before Implementation for Level 3-4 tasks
9. **Detect platform** and adapt commands automatically
10. **Block Implementation** if QA fails or Creative Phase incomplete

---

##  Common Workflow Violations (Learn from These)

### Violation 1: Starting Without Planning
```diff
 BAD:
User: "Refactor the authentication system"
AI: [Immediately rewrites auth code]

 GOOD:
User: "Refactor the authentication system"
AI: "Let me analyze the current system first:
     - Current: Session-based with cookies
     - Issues: No token refresh, vulnerable to CSRF
     - Options: Keep sessions vs migrate to JWT
     - Impact: Affects 15 files, requires DB changes

     Shall I proceed with a detailed migration plan?"
```

### Violation 2: Adding Unplanned Features
```diff
 BAD:
User: "Add a search bar to the header"
AI: [Adds search bar + autocomplete + search history + filters + advanced search]

 GOOD:
User: "Add a search bar to the header"
AI: [Adds only basic search bar as requested]
     "Search bar complete. Would you like to discuss:
      - Autocomplete suggestions?
      - Search history?
      - Advanced filters?"
```

### Violation 3: Not Stopping at Agreed Scope
```diff
 BAD:
User: "Fix the login button styling"
AI: [Fixes button + refactors entire CSS + updates all components]

 GOOD:
User: "Fix the login button styling"
AI: [Fixes only the login button]
     "Login button fixed. I noticed other styling issues:
      - Header alignment is off
      - Footer needs responsive updates
      Should we address these in the next phase?"
```

---

##  Important Notes

- **Simple tasks** (Level 1) can skip formal phases, but still follow coding standards
- **Context files are optional** for simple projects but highly recommended for complex ones
- **This workflow complements** your detailed coding standards, it doesn't replace them
- **Always follow** security and quality standards from `100-core.mdc` regardless of workflow phase
- **QA Validation is mandatory** for Level 2+ tasks before Implementation
- **Creative Phase is mandatory** for Level 3-4 tasks before Implementation
- **Platform detection** happens automatically - adapt commands accordingly
- **QA command ("QA")** can interrupt any process and takes immediate precedence

---