title: "Core Workflows" description: "TDD with Run Modes + hooks, incremental refactoring, Debug Mode, Parallel Agents, and progressive enhancement." section: "Full Guide" readTime: "13 min"

Core Workflows

These workflows use skills and hooks for autonomous iteration — maximizing productivity while maintaining code quality.

TDD with Run Modes + Hooks

The most powerful Cursor workflow: write tests, implement, auto-iterate until all tests pass.

Pick a Run Mode (Settings > Agents > Approvals & Execution):

• Auto-review (recommended): allowlisted calls run immediately, shell commands run in a sandbox where possible, and a classifier reviews the rest
• Allowlist: allowlisted commands such as npm test and npm run run without prompts; everything else asks
• Run Everything: no prompts at all; avoid on machines with credentials

Configure a stop hook (.cursor/hooks.json):

{
  "version": 1,
  "hooks": {
    "stop": [
      { "command": ".cursor/hooks/stop-when-tests-pass.sh", "loop_limit": 5 }
    ]
  }
}

#!/bin/bash
cat > /dev/null   # consume stdin JSON
if npm test --silent >/dev/null 2>&1; then
  echo '{}'       # tests pass: no follow-up, the agent stops
else
  echo '{"followup_message": "Tests are still failing. Run npm test and fix the failures."}'
fi

When the agent stops, a followup_message is submitted automatically as the next user message. loop_limit (default 5) caps how many times that can repeat.

TDD prompt template:

Write tests first, then implementation, then run tests and fix until passing.

Context:
- Test framework: Vitest
- Coverage target: >80%
- Edge cases: null, undefined, empty array, large inputs

Task: Implement markdown-to-HTML converter

Requirements:
1. Tests: basic markdown, edge cases, XSS attempts, performance (10MB input)
2. Implementation: use marked library, sanitize with DOMPurify
3. Agent workflow:
   - Generate test suite
   - Wait for test approval
   - Implement
   - Run tests automatically
   - Fix failures iteratively
   - Report when all pass

DO NOT PROCEED to implementation until tests are reviewed.

Flow with hooks:

1. Agent creates the test file
2. You review and approve
3. Agent implements and runs npm test
4. Tests fail, so the stop hook sends a follow-up and the agent fixes them
5. Repeats until tests pass or loop_limit is hit
6. Agent reports completion

Using a Test-Loop Skill

Instead of describing the TDD workflow every time, put it in a skill (.cursor/skills/test-loop/SKILL.md, see Setup) and invoke it:

/test-loop

Implement password reset feature with comprehensive tests.

The agent may also apply the skill on its own when the task matches its description.

Incremental Refactoring Pattern

Never do this:

Refactor this 500-line file to use modern patterns.

Result: massive diff, unverifiable, likely breaks edge cases.

Always do this (incremental). Start in Plan Mode (Shift+Tab) so the agent researches and asks questions before touching code:

Step 1: Analyze @src/routes/users.ts
Identify: code smells, tech debt, performance issues, test coverage gaps.
Wait for review before proceeding.

Step 2: Plan refactoring into 3-5 atomic steps.
Show effort estimate, risks, rollback plan per step.
Wait for approval.

Step 3: Execute step 1 only. Show diff. Run tests. Wait for approval.

Step 4: Repeat for remaining steps.

Express to Fastify migration example:

@src/routes/

Phase 1: Analysis — list all routes, middleware, Express-specific features.
Phase 2: Plan 5-step migration with rollback plan per step.
Phase 3: Create src/fastify-server.ts on port 3001 (Express stays on 3000).
         Test: curl localhost:3001/health. Wait for approval.
[Continue one route group at a time...]

Constraints:
- No breaking changes to API contract
- Backward compatibility for 2 weeks (both servers running)

Debug Mode Workflow

Use when a bug is elusive, intermittent, or in async code. Pick Debug from the mode picker (or rotate with Shift+Tab).

How it works:

1. Describe the bug with exact error, environment, and reproduction steps
2. Agent reads relevant files and proposes several possible root causes
3. Agent adds log statements that send data to a local debug server in the Cursor extension
4. You reproduce the bug following the agent's steps
5. Agent analyzes the collected logs to find the actual cause
6. Agent makes a small, targeted fix
7. You re-run the steps to confirm, and the agent removes the logging

For race conditions and other intermittent issues, reproducing the bug several times gives the agent more evidence.

Example prompt:

Bug: User sessions randomly expire after ~5 minutes (expected: 24 hours)

Framework: Express + express-session
Session store: Redis
Auth: JWT + refresh tokens
Environment: Production only (dev works fine)

Hypotheses to investigate:
- Redis connection issues (pool exhaustion?)
- Session cookie config (SameSite, Secure flags)
- Clock drift between servers
- Race condition in token refresh

Parallel Agents and Worktrees

Run multiple agents at once to explore different approaches. Best for architecture decisions or risky refactors. Cursor creates and manages the git worktrees for you, so each agent works in its own checkout and your main checkout stays clean.

From the IDE:

• /worktree <task> runs the rest of that chat in an isolated checkout
• /best-of-n model1,model2,... <task> runs the same task on several models, each in its own worktree
• /apply-worktree brings a worktree's changes into your main checkout
• /delete-worktree cleans up when you're done
• git worktree list shows all worktrees

/best-of-n sonnet,gpt,composer implement passwordless login with passkeys

Best-of-N only compares results; it doesn't merge anything. Pick a winner, then commit from its worktree or run /apply-worktree. You can also start an agent in a worktree from the Agents Window.

To prepare each worktree (install dependencies, copy .env), add .cursor/worktrees.json; see Setup. Cursor prunes old worktrees automatically (default cap 25 per machine in Cursor 3.5+).

For different tasks in parallel, open separate agents, one per task. Multi-root workspaces disable worktrees.

Cloud Agents run the same way in isolated cloud VMs. Choose Cloud in the dropdown under the agent input, or start them from cursor.com/agents, Slack, Linear, or an @cursor comment on a PR.

Progressive Enhancement Pattern

Build features in phases — ship Phase 1 while building Phase 2.

Implement search feature in 4 phases:

Phase 1: MVP
- Input field + search button + results list
- No filters, sorting, pagination
Generate code + tests. Run tests. Wait for approval.

Phase 2: Add features
- Filters (category, price range)
- Sorting (relevance, date, price)
Generate code + tests. Run tests. Wait for approval.

Phase 3: Optimize
- Debounced input (300ms)
- Loading/empty/error states
- Keyboard shortcuts (Cmd+K to focus)
Generate code + tests. Run tests. Wait for approval.

Phase 4: Polish
- Infinite scroll, highlight terms, recent searches (localStorage)
Generate final version + tests.

Essential Keyboard Shortcuts

See the keyboard shortcut reference for the full list.