AI-First DevOps Toolkit Rules

A structured workflow system for AI-driven development that uses Plan/Agent modes, scratchpad-based task management, and comprehensive memory tracking to handle the entire development lifecycle.

Core Workflow

Maintain three critical files for all interactions:

1. `.cursor/memories.md` - Exhaustive log of all development decisions and changes

2. `.cursor/rules/lessons-learned.mdc` - Categorized solutions and best practices

3. `.cursor/scratchpad.md` - Active task tracking and session context

Always use chain-of-thought reasoning for problem-solving and cross-reference existing documentation before making decisions.

Mode System

Plan Mode

**Trigger:** User says "plan" or you need to gather requirements

1. Create a session entry in `.cursor/scratchpad.md`:

```

Mode: PLAN 🎯

Current Task: [specific task from user input]

Understanding: [requirements and constraints]

Questions: [numbered list, minimum 3]

Confidence: [percentage based on unknowns]

Next Steps: [bullet points]

```

2. Generate at least 3 clarifying questions about the task

3. After each user response, recalculate confidence level

4. Continue questioning until confidence reaches ≥ 95%

5. Only transition to Agent mode when all requirements are clear

Agent Mode

**Trigger:** User says "agent" or confidence is ≥ 95%

**Pre-activation checklist:**

**Enabled capabilities:**

Task Management

Scratchpad Format

Maintain `.cursor/scratchpad.md` with this structure:

```

Current Phase: [PHASE-X]

Mode Context: [PLAN/AGENT]

Status: [Active/Planning/Review]

Confidence: [percentage]

Last Updated: [version identifier]

Tasks:

[ID-001] Task description

Status: [status marker] Priority: [High/Medium/Low]

Dependencies: [list of blocking task IDs]

Progress Notes: [version] Implementation details and decisions

```

Status Markers

Task IDs

Use sequential format: `[ID-001]`, `[ID-002]`, etc.

Documentation Protocol

Memories File (.cursor/memories.md)

Update after **every interaction** with single-line entries:

**Development entries:**

```

[Version] Development: [Exhaustive description of changes, decisions, implementation details, and outcomes]

```

**Manual entries (when user uses "mems" keyword):**

```

[Version] Manual Update: [Planning discussions, requirements, strategic decisions]

```

Lessons Learned File (.cursor/rules/lessons-learned.mdc)

Format: `Category: Issue → Solution → Impact`

**Categories:**

**Example:**

```

Error Resolution: React hydration mismatch with Date.now() → Used useEffect for client-only rendering → Eliminated hydration errors in dev console

```

Phase Documentation

When a phase is completed, create `/docs/phases/PHASE-X/[FEATURE-NAME].md` containing:

Development Rules

1. **Preserve comments:** Keep all existing code comments. Fix typos and adjust to new code, but never remove them

2. **Add descriptive comments:** Include inline comments for complex logic to aid long-term memory

3. **Use Pydantic models:** Enforce type safety with Pydantic models for data structures

4. **Follow established patterns:** Check memories for existing architectural decisions and patterns

5. **Ignore nodejs folder:** The `./nodejs` folder is early-stage and should be ignored

Mode Selection Guide

Implementation Mode (New Features)

1. Start in Plan mode to gather requirements

2. Ask clarifying questions until 95%+ confidence

3. Switch to Agent mode for implementation

4. Update all documentation files

Bug Fix Mode

1. Start in Plan mode to understand the issue

2. Use chain-of-thought reasoning to diagnose root cause

3. Propose solution and validate approach

4. Switch to Agent mode for fixes

5. Document resolution in lessons-learned.mdc

Confidence Calculation

Calculate confidence as: `(answered_questions / total_questions) × 100`

**Factors that lower confidence:**

**Factors that raise confidence:**

Interaction Examples

**Starting a new feature:**

```

User: "I need to add user authentication"

AI: [Creates Plan mode session in scratchpad]

AI: "I have some questions to ensure we implement this correctly:

1. What authentication method do you prefer? (JWT, sessions, OAuth)

2. Do you need multi-factor authentication?

3. What user roles and permissions are required?

[Current confidence: 40%]"

```

**Switching to Agent mode:**

```

User: "agent"

AI: [Checks scratchpad - confidence 96%, all questions answered]

AI: [Switches to Agent mode]

AI: "Implementing user authentication with JWT tokens and role-based access control. Starting with Pydantic models for user schemas..."

[Creates files, updates memories.md, progresses through scratchpad tasks]

```

Key Principles