ma7dev/README.md

## README.md

      
    Raw
  

              README.md
            
          
    This is my latest cursor 2.0 setup to utilize cursor fully
I am using Cursor + Task Master (as an MCP). In addition, I am using the following MCPs: Perplexity (to better search the web) and context7 (to retrieve technical docs on the fly)
download the rules with a oneliner
curl -s https://gist.github.com/ma7dev/3962cb563e5fc1a16cba04a5ef412672 \
  | grep -oE '/ma7dev/3962cb563e5fc1a16cba04a5ef412672/raw/[0-9a-f]+/[A-Za-z0-9_.-]+\.mdc' \
  | sed 's#^#https://gist.github.com#' \
  | xargs -n1 -I{} sh -c 'curl -sL "$1" -o "$(basename "$1")"' _ {}
# starting from project_details.mdc that describes the project

update @.cursor/rules/project_details.mdc to have explicit, clear, and easy to follow details for a codegen to implement

use perplexity to get the latest information

I want this to be a quick PoC

---

# for each task

## (plan mode) - Opus 4.5
make a plan to do next_task

## (build mode) - Opus 4.5


## cursor_rules.mdc
---
description: Guidelines for creating and maintaining Cursor rules to ensure consistency and effectiveness.
globs: .cursor/rules/*.mdc
alwaysApply: true
---

- **Required Rule Structure:**
  ```markdown
  ---
  description: Clear, one-line description of what the rule enforces
  globs: path/to/files/*.ext, other/path/**/*
  alwaysApply: boolean
  ---

  - **Main Points in Bold**
    - Sub-points with details
    - Examples and explanations
  ```

- **File References:**
  - Use `[filename](mdc:path/to/file)` ([filename](mdc:filename)) to reference files
  - Example: [prisma.mdc](mdc:.cursor/rules/prisma.mdc) for rule references
  - Example: [schema.prisma](mdc:prisma/schema.prisma) for code references

- **Code Examples:**
  - Use language-specific code blocks
  ```typescript
  // ✅ DO: Show good examples
  const goodExample = true;

  // ❌ DON'T: Show anti-patterns
  const badExample = false;
  ```

- **Rule Content Guidelines:**
  - Start with high-level overview
  - Include specific, actionable requirements
  - Show examples of correct implementation
  - Reference existing code when possible
  - Keep rules DRY by referencing other rules

- **Rule Maintenance:**
  - Update rules when new patterns emerge
  - Add examples from actual codebase
  - Remove outdated patterns
  - Cross-reference related rules

- **Best Practices:**
  - Use bullet points for clarity
  - Keep descriptions concise
  - Include both DO and DON'T examples
  - Reference actual code over theoretical examples
  - Use consistent formatting across rules

## mb.mdc
---
alwaysApply: true
---

# Memory Bank Protocol

This document defines how the AI agent manages project memory. Follow these rules exactly.

---

## CRITICAL RULES

### Rule 1: Always Update Existing Files

**DO:**
- Update existing `.cursor/rules/*.mdc` files when information changes
- Modify content in place rather than creating duplicate files
- Check if a file exists before any write operation

**DO NOT:**
- Create new rule files if one already exists for that purpose
- Duplicate information across multiple files
- Create files outside `.cursor/rules/` for project memory

**Exception:** Create new files only when starting a fresh project with no existing rules.

### Rule 2: Use Taskmaster-AI MCP for Task Management

Use `taskmaster-ai` MCP server for all task tracking instead of manual progress files.

**Core commands:**
- `get_tasks` - List all tasks and their status
- `next_task` - Get the next task to work on
- `set_task_status` - Mark tasks as done, in-progress, etc.
- `add_task` - Add new tasks with AI structuring
- `update_subtask` - Log progress on subtasks

**After ANY code change:**
1. Update relevant task status via `set_task_status`
2. If working on subtask, use `update_subtask` to log findings

### Rule 3: Use Perplexity MCP for Research

Use `perplexity` MCP server to get up-to-date information before implementing unfamiliar patterns.

**When to use:**
- Before implementing new libraries or frameworks
- When debugging obscure errors
- For latest best practices on tech stack decisions
- When documentation seems outdated

**How to use:**
```
mcp_perplexity_perplexity_search_web(query="your question", recency="month")
```

---

## DIRECTORY STRUCTURE

```
.cursor/rules/                  # Agent operational files (instructions + state)
├── mb.mdc                      # This file - operational protocol
├── active_context.mdc          # Current work focus (agent tracks tasks here)
└── project_details.mdc         # Existing file

.taskmaster/docs/               # Taskmaster convention
└── milestones.md               # Project milestones (used for PRD/task generation)

docs/                           # Onboarding & context documentation
├── project_brief.md            # Core requirements and goals
├── product_context.md          # Why the project exists, who it's for
├── system_patterns.md          # Architecture decisions
└── tech_context.md             # Tech stack and environment
```

---

## CORE FILES REFERENCE

### Agent Files (.cursor/rules/)

**active_context.mdc**
- Purpose: Current work focus, recent decisions, immediate next steps
- Update when: Starting new work or making significant decisions
- Frontmatter: `alwaysApply: true`

### Taskmaster Files (.taskmaster/docs/)

**milestones.md**
- Purpose: Define project phases and objectives for Taskmaster
- Update when: Starting a new phase or changing project direction
- Usage: Feed to `parse_prd` to generate tasks

### Documentation Files (docs/)

**project_brief.md** - Core requirements and goals
**product_context.md** - Why the project exists, who it's for
**system_patterns.md** - Architecture decisions and design patterns
**tech_context.md** - Tech stack, dependencies, environment setup

---

## TASKMASTER WORKFLOW

### Phase 1: Planning

Use this phase when starting a new milestone or major feature.

1. **Research** - Use Perplexity MCP for unfamiliar tech
2. **Update docs/** - Fill in project_brief, tech_context, system_patterns
3. **Update milestones** - Edit `.taskmaster/docs/milestones.md` with objectives
4. **Generate tasks** - Run `parse_prd` with milestones file
5. **View tasks** - Run `get_tasks` or `npx task-studio@latest`

### Phase 2: Execution

Repeat this cycle for each task.

1. **Get next task** - `next_task`
2. **Set in-progress** - `set_task_status` with status "in-progress"
3. **Implement** - Code the solution
4. **Validate** - Ensure changes work
5. **Update context** - Update `active_context.mdc` with findings
6. **Mark done** - `set_task_status` with status "done"
7. **GIT COMMIT** - Always commit before moving to next task
8. **Repeat** - Go to step 1

### Phase 3: Updating Plan

After completing a milestone.

1. **Review work** - Check what was completed
2. **Update docs/** - Add new learnings to documentation
3. **Update milestones** - Add next phase to `.taskmaster/docs/milestones.md`
4. **Re-generate tasks** - Run `parse_prd` for new phase

---

## TASKMASTER MCP COMMANDS

| Command | Purpose |
|---------|---------|
| `get_tasks` | List all tasks and status |
| `next_task` | Get next available task based on dependencies |
| `set_task_status` | Mark task as done/in-progress/pending |
| `add_task` | Add new task with AI structuring |
| `update_subtask` | Log progress and findings on subtasks |
| `parse_prd` | Generate tasks from PRD/milestones |
| `expand_task` | Break down complex task into subtasks |
| `analyze_project_complexity` | Analyze which tasks need breakdown |

---

## WORKFLOW DIAGRAM

```mermaid
flowchart TD
    Start["Receive Task"] --> Read["Read .cursor/rules/*.mdc + docs/"]
    Read --> Check{"Taskmaster initialized?"}
    Check -- No --> Plan["Phase 1: Planning"]
    Plan --> Parse["parse_prd from milestones.md"]
    Parse --> GetTask
    Check -- Yes --> GetTask["next_task"]
    GetTask --> SetProgress["set_task_status: in-progress"]
    SetProgress --> Implement["Implement solution"]
    Implement --> Validate["Validate changes"]
    Validate --> UpdateContext["Update active_context.mdc"]
    UpdateContext --> SetDone["set_task_status: done"]
    SetDone --> Commit["GIT COMMIT"]
    Commit --> More{"More tasks?"}
    More -- Yes --> GetTask
    More -- No --> UpdatePlan["Phase 3: Update milestones"]
    UpdatePlan --> Parse
```

---

## TASK COMPLETION CHECKLIST

Run through this checklist after every task:

1. [ ] Code changes validated and working
2. [ ] Task status updated via Taskmaster-AI MCP
3. [ ] `active_context.mdc` updated if work focus changed
4. [ ] Git committed before moving to next task
5. [ ] No new rule files created (unless project was empty)

---

## FILE UPDATE TRIGGERS

| Event | Action |
|-------|--------|
| Any code change | Update task status via Taskmaster-AI |
| New work focus | Update `active_context.mdc` |
| Architecture decision | Update `docs/system_patterns.md` |
| New dependency added | Update `docs/tech_context.md` |
| Requirements change | Update `docs/project_brief.md` |
| New milestone/phase | Update `.taskmaster/docs/milestones.md` |

---

## SESSION START PROCEDURE

At the start of every session:

1. Read ALL files in `.cursor/rules/` directory
2. Read ALL files in `docs/` directory
3. Use `get_tasks` from Taskmaster-AI to see current task status
4. Review `active_context.mdc` for current work focus
5. Proceed with user's request

---

## MEMORY BANK UPDATE COMMAND

When user says "update memory bank":

1. Review every file in `.cursor/rules/`
2. Review every file in `docs/`
3. Update each file to reflect current project state
4. Pay special attention to `active_context.mdc`
5. Sync task status with Taskmaster-AI
6. Report what was updated

---

## PRINCIPLES

1. **Update, don't create** - Modify existing files rather than making new ones
2. **Use MCP tools** - Taskmaster-AI for tasks, Perplexity for research
3. **Be explicit** - Write clearly so future sessions understand immediately
4. **Minimal structure** - Only create what's needed, avoid over-organization
5. **Always commit** - Git commit after every completed task

## mcp.json
{
  "mcpServers": {
    "perplexity": {
      "env": {
        "PERPLEXITY_API_KEY": "pplx-XXXX",
        "PERPLEXITY_MODEL": "sonar"
      },
      "command": "uvx",
      "args": [
        "perplexity-mcp"
      ]
    },
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    },
    "taskmaster-ai": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "--package=task-master-ai",
        "task-master-ai"
      ],
      "env": {
        "PERPLEXITY_API_KEY": "pplx-XXX"
      }
    }
  }
}

## self_improve.mdc
---
description: Guidelines for continuously improving Cursor rules based on emerging code patterns and best practices.
globs: **/*
alwaysApply: true
---

- **Rule Improvement Triggers:**
  - New code patterns not covered by existing rules
  - Repeated similar implementations across files
  - Common error patterns that could be prevented
  - New libraries or tools being used consistently
  - Emerging best practices in the codebase

- **Analysis Process:**
  - Compare new code with existing rules
  - Identify patterns that should be standardized
  - Look for references to external documentation
  - Check for consistent error handling patterns
  - Monitor test patterns and coverage

- **Rule Updates:**
  - **Add New Rules When:**
    - A new technology/pattern is used in 3+ files
    - Common bugs could be prevented by a rule
    - Code reviews repeatedly mention the same feedback
    - New security or performance patterns emerge

  - **Modify Existing Rules When:**
    - Better examples exist in the codebase
    - Additional edge cases are discovered
    - Related rules have been updated
    - Implementation details have changed

- **Example Pattern Recognition:**
  ```typescript
  // If you see repeated patterns like:
  const data = await prisma.user.findMany({
    select: { id: true, email: true },
    where: { status: 'ACTIVE' }
  });

  // Consider adding to [prisma.mdc](mdc:.cursor/rules/prisma.mdc):
  // - Standard select fields
  // - Common where conditions
  // - Performance optimization patterns
  ```

- **Rule Quality Checks:**
  - Rules should be actionable and specific
  - Examples should come from actual code
  - References should be up to date
  - Patterns should be consistently enforced

- **Continuous Improvement:**
  - Monitor code review comments
  - Track common development questions
  - Update rules after major refactors
  - Add links to relevant documentation
  - Cross-reference related rules

- **Rule Deprecation:**
  - Mark outdated patterns as deprecated
  - Remove rules that no longer apply
  - Update references to deprecated rules
  - Document migration paths for old patterns

- **Documentation Updates:**
  - Keep examples synchronized with code
  - Update references to external docs
  - Maintain links between related rules
  - Document breaking changes
Follow [cursor_rules.mdc](mdc:.cursor/rules/cursor_rules.mdc) for proper rule formatting and structure.
	---
	description: Guidelines for creating and maintaining Cursor rules to ensure consistency and effectiveness.
	globs: .cursor/rules/*.mdc
	alwaysApply: true
	---

	- Required Rule Structure:
	```markdown
	---
	description: Clear, one-line description of what the rule enforces
	globs: path/to/files/.ext, other/path//
	alwaysApply: boolean
	---

	- Main Points in Bold
	- Sub-points with details
	- Examples and explanations
	```

	- File References:
	- Use `[filename](mdc:path/to/file)` ([filename](mdc:filename)) to reference files
	- Example: [prisma.mdc](mdc:.cursor/rules/prisma.mdc) for rule references
	- Example: [schema.prisma](mdc:prisma/schema.prisma) for code references

	- Code Examples:
	- Use language-specific code blocks
	```typescript
	// ✅ DO: Show good examples
	const goodExample = true;

	// ❌ DON'T: Show anti-patterns
	const badExample = false;
	```

	- Rule Content Guidelines:
	- Start with high-level overview
	- Include specific, actionable requirements
	- Show examples of correct implementation
	- Reference existing code when possible
	- Keep rules DRY by referencing other rules

	- Rule Maintenance:
	- Update rules when new patterns emerge
	- Add examples from actual codebase
	- Remove outdated patterns
	- Cross-reference related rules

	- Best Practices:
	- Use bullet points for clarity
	- Keep descriptions concise
	- Include both DO and DON'T examples
	- Reference actual code over theoretical examples
	- Use consistent formatting across rules
	---
	alwaysApply: true
	---

	# Memory Bank Protocol

	This document defines how the AI agent manages project memory. Follow these rules exactly.

	---

	## CRITICAL RULES

	### Rule 1: Always Update Existing Files

	DO:
	- Update existing `.cursor/rules/*.mdc` files when information changes
	- Modify content in place rather than creating duplicate files
	- Check if a file exists before any write operation

	DO NOT:
	- Create new rule files if one already exists for that purpose
	- Duplicate information across multiple files
	- Create files outside `.cursor/rules/` for project memory

	Exception: Create new files only when starting a fresh project with no existing rules.

	### Rule 2: Use Taskmaster-AI MCP for Task Management

	Use `taskmaster-ai` MCP server for all task tracking instead of manual progress files.

	Core commands:
	- `get_tasks` - List all tasks and their status
	- `next_task` - Get the next task to work on
	- `set_task_status` - Mark tasks as done, in-progress, etc.
	- `add_task` - Add new tasks with AI structuring
	- `update_subtask` - Log progress on subtasks

	After ANY code change:
	1. Update relevant task status via `set_task_status`
	2. If working on subtask, use `update_subtask` to log findings

	### Rule 3: Use Perplexity MCP for Research

	Use `perplexity` MCP server to get up-to-date information before implementing unfamiliar patterns.

	When to use:
	- Before implementing new libraries or frameworks
	- When debugging obscure errors
	- For latest best practices on tech stack decisions
	- When documentation seems outdated

	How to use:
	```
	mcp_perplexity_perplexity_search_web(query="your question", recency="month")
	```

	---

	## DIRECTORY STRUCTURE

	```
	.cursor/rules/ # Agent operational files (instructions + state)
	├── mb.mdc # This file - operational protocol
	├── active_context.mdc # Current work focus (agent tracks tasks here)
	└── project_details.mdc # Existing file

	.taskmaster/docs/ # Taskmaster convention
	└── milestones.md # Project milestones (used for PRD/task generation)

	docs/ # Onboarding & context documentation
	├── project_brief.md # Core requirements and goals
	├── product_context.md # Why the project exists, who it's for
	├── system_patterns.md # Architecture decisions
	└── tech_context.md # Tech stack and environment
	```

	---

	## CORE FILES REFERENCE

	### Agent Files (.cursor/rules/)

	active_context.mdc
	- Purpose: Current work focus, recent decisions, immediate next steps
	- Update when: Starting new work or making significant decisions
	- Frontmatter: `alwaysApply: true`

	### Taskmaster Files (.taskmaster/docs/)

	milestones.md
	- Purpose: Define project phases and objectives for Taskmaster
	- Update when: Starting a new phase or changing project direction
	- Usage: Feed to `parse_prd` to generate tasks

	### Documentation Files (docs/)

	project_brief.md - Core requirements and goals
	product_context.md - Why the project exists, who it's for
	system_patterns.md - Architecture decisions and design patterns
	tech_context.md - Tech stack, dependencies, environment setup

	---

	## TASKMASTER WORKFLOW

	### Phase 1: Planning

	Use this phase when starting a new milestone or major feature.

	1. Research - Use Perplexity MCP for unfamiliar tech
	2. Update docs/ - Fill in project_brief, tech_context, system_patterns
	3. Update milestones - Edit `.taskmaster/docs/milestones.md` with objectives
	4. Generate tasks - Run `parse_prd` with milestones file
	5. View tasks - Run `get_tasks` or `npx task-studio@latest`

	### Phase 2: Execution

	Repeat this cycle for each task.

	1. Get next task - `next_task`
	2. Set in-progress - `set_task_status` with status "in-progress"
	3. Implement - Code the solution
	4. Validate - Ensure changes work
	5. Update context - Update `active_context.mdc` with findings
	6. Mark done - `set_task_status` with status "done"
	7. GIT COMMIT - Always commit before moving to next task
	8. Repeat - Go to step 1

	### Phase 3: Updating Plan

	After completing a milestone.

	1. Review work - Check what was completed
	2. Update docs/ - Add new learnings to documentation
	3. Update milestones - Add next phase to `.taskmaster/docs/milestones.md`
	4. Re-generate tasks - Run `parse_prd` for new phase

	---

	## TASKMASTER MCP COMMANDS

	\| Command \| Purpose \|
	\|---------\|---------\|
	\| `get_tasks` \| List all tasks and status \|
	\| `next_task` \| Get next available task based on dependencies \|
	\| `set_task_status` \| Mark task as done/in-progress/pending \|
	\| `add_task` \| Add new task with AI structuring \|
	\| `update_subtask` \| Log progress and findings on subtasks \|
	\| `parse_prd` \| Generate tasks from PRD/milestones \|
	\| `expand_task` \| Break down complex task into subtasks \|
	\| `analyze_project_complexity` \| Analyze which tasks need breakdown \|

	---

	## WORKFLOW DIAGRAM

	```mermaid
	flowchart TD
	Start["Receive Task"] --> Read["Read .cursor/rules/*.mdc + docs/"]
	Read --> Check{"Taskmaster initialized?"}
	Check -- No --> Plan["Phase 1: Planning"]
	Plan --> Parse["parse_prd from milestones.md"]
	Parse --> GetTask
	Check -- Yes --> GetTask["next_task"]
	GetTask --> SetProgress["set_task_status: in-progress"]
	SetProgress --> Implement["Implement solution"]
	Implement --> Validate["Validate changes"]
	Validate --> UpdateContext["Update active_context.mdc"]
	UpdateContext --> SetDone["set_task_status: done"]
	SetDone --> Commit["GIT COMMIT"]
	Commit --> More{"More tasks?"}
	More -- Yes --> GetTask
	More -- No --> UpdatePlan["Phase 3: Update milestones"]
	UpdatePlan --> Parse
	```

	---

	## TASK COMPLETION CHECKLIST

	Run through this checklist after every task:

	1. [ ] Code changes validated and working
	2. [ ] Task status updated via Taskmaster-AI MCP
	3. [ ] `active_context.mdc` updated if work focus changed
	4. [ ] Git committed before moving to next task
	5. [ ] No new rule files created (unless project was empty)

	---

	## FILE UPDATE TRIGGERS

	\| Event \| Action \|
	\|-------\|--------\|
	\| Any code change \| Update task status via Taskmaster-AI \|
	\| New work focus \| Update `active_context.mdc` \|
	\| Architecture decision \| Update `docs/system_patterns.md` \|
	\| New dependency added \| Update `docs/tech_context.md` \|
	\| Requirements change \| Update `docs/project_brief.md` \|
	\| New milestone/phase \| Update `.taskmaster/docs/milestones.md` \|

	---

	## SESSION START PROCEDURE

	At the start of every session:

	1. Read ALL files in `.cursor/rules/` directory
	2. Read ALL files in `docs/` directory
	3. Use `get_tasks` from Taskmaster-AI to see current task status
	4. Review `active_context.mdc` for current work focus
	5. Proceed with user's request

	---

	## MEMORY BANK UPDATE COMMAND

	When user says "update memory bank":

	1. Review every file in `.cursor/rules/`
	2. Review every file in `docs/`
	3. Update each file to reflect current project state
	4. Pay special attention to `active_context.mdc`
	5. Sync task status with Taskmaster-AI
	6. Report what was updated

	---

	## PRINCIPLES

	1. Update, don't create - Modify existing files rather than making new ones
	2. Use MCP tools - Taskmaster-AI for tasks, Perplexity for research
	3. Be explicit - Write clearly so future sessions understand immediately
	4. Minimal structure - Only create what's needed, avoid over-organization
	5. Always commit - Git commit after every completed task
	{
	"mcpServers": {
	"perplexity": {
	"env": {
	"PERPLEXITY_API_KEY": "pplx-XXXX",
	"PERPLEXITY_MODEL": "sonar"
	},
	"command": "uvx",
	"args": [
	"perplexity-mcp"
	]
	},
	"context7": {
	"url": "https://mcp.context7.com/mcp"
	},
	"taskmaster-ai": {
	"type": "stdio",
	"command": "npx",
	"args": [
	"-y",
	"--package=task-master-ai",
	"task-master-ai"
	],
	"env": {
	"PERPLEXITY_API_KEY": "pplx-XXX"
	}
	}
	}
	}
	---
	description: Guidelines for continuously improving Cursor rules based on emerging code patterns and best practices.
	globs: */
	alwaysApply: true
	---

	- Rule Improvement Triggers:
	- New code patterns not covered by existing rules
	- Repeated similar implementations across files
	- Common error patterns that could be prevented
	- New libraries or tools being used consistently
	- Emerging best practices in the codebase

	- Analysis Process:
	- Compare new code with existing rules
	- Identify patterns that should be standardized
	- Look for references to external documentation
	- Check for consistent error handling patterns
	- Monitor test patterns and coverage

	- Rule Updates:
	- Add New Rules When:
	- A new technology/pattern is used in 3+ files
	- Common bugs could be prevented by a rule
	- Code reviews repeatedly mention the same feedback
	- New security or performance patterns emerge

	- Modify Existing Rules When:
	- Better examples exist in the codebase
	- Additional edge cases are discovered
	- Related rules have been updated
	- Implementation details have changed

	- Example Pattern Recognition:
	```typescript
	// If you see repeated patterns like:
	const data = await prisma.user.findMany({
	select: { id: true, email: true },
	where: { status: 'ACTIVE' }
	});

	// Consider adding to [prisma.mdc](mdc:.cursor/rules/prisma.mdc):
	// - Standard select fields
	// - Common where conditions
	// - Performance optimization patterns
	```

	- Rule Quality Checks:
	- Rules should be actionable and specific
	- Examples should come from actual code
	- References should be up to date
	- Patterns should be consistently enforced

	- Continuous Improvement:
	- Monitor code review comments
	- Track common development questions
	- Update rules after major refactors
	- Add links to relevant documentation
	- Cross-reference related rules

	- Rule Deprecation:
	- Mark outdated patterns as deprecated
	- Remove rules that no longer apply
	- Update references to deprecated rules
	- Document migration paths for old patterns

	- Documentation Updates:
	- Keep examples synchronized with code
	- Update references to external docs
	- Maintain links between related rules
	- Document breaking changes
	Follow [cursor_rules.mdc](mdc:.cursor/rules/cursor_rules.mdc) for proper rule formatting and structure.