11-Cursor-Rules

project-overview.mdc

---
description: High-level project overview kept in sync with docs/PROJECT_CONTEXT.md.
globs:
alwaysApply: true
---

# Project Overview

This project is an **AI Coding Agent Workspace** — a structured platform for running AI coding agents on real software projects.

## Always do
- Inspect RAG context and `docs/PROJECT_MAP.md` before planning or editing.
- Understand the route ↔ controller ↔ model ↔ table relationship before changing any of them.
- Check database relationships before changing models.
- Add or update tests for non-trivial changes.
- Update docs after changes (PROJECT_MAP, DATABASE_SCHEMA, CHANGELOG_AI, ARCHITECTURE_DIAGRAMS).
- Prefer small safe changes; one logical concern per commit.
- Show debug output and reasoning in the console.
- Keep the iPhone-first API clean.

## Never do
- Hardcode secrets.
- Expose API keys in code, logs, docs, or responses.
- Run dangerous shell commands.
- Break existing routes silently.
- Push to remote automatically.

architecture.mdc

---
description: Architectural rules and boundaries.
alwaysApply: true
---

# Architecture

- Backend is Laravel 11. Controllers stay thin; business logic in services.
- Services are constructor-injected. No facades inside services; facades only in controllers/jobs.
- Strict types declared at the top of every PHP file.
- One agent per project workspace at a time (Redis lock).
- Provider-agnostic agents implement AgentProviderInterface.
- iPhone-first API: paginated, SSE for live events, server-rendered diffs.

database.mdc

---
description: Database conventions.
alwaysApply: true
---

# Database

- PostgreSQL 16 + pgvector. MySQL-compatible fallback for RAG via Qdrant.
- Every migration is reversible.
- Use foreign keys with explicit `cascadeOnDelete` or `nullOnDelete`.
- Index columns used in `WHERE`, `ORDER BY`, and FKs.
- Soft-delete only when the product truly needs trash/restore semantics.
- JSON columns for unstructured payloads (`metadata_json`, `payload_json`). Add a comment in the migration explaining the shape.

rag-system.mdc

---
description: RAG system rules.
alwaysApply: true
---

# RAG

- All retrieval goes through RagContextService.
- Embedding model: text-embedding-3-large (3072 dims). Do not hardcode dimension elsewhere.
- Chunking is language-aware (see docs/RAG_SYSTEM.md).
- Re-embed only when content_hash changes.
- Emit rag_search_started and rag_search_completed events around every retrieval.
- The agent must never guess when context exists.

agent-workflow.mdc

---
description: Agent run lifecycle.
alwaysApply: true
---

# Agent Workflow

Lifecycle: draft → queued → running ↔ {paused, waiting_for_user} → completed | failed | cancelled.

- Always acquire the workspace lock before any action.
- Always create a pre_run snapshot.
- Always create a branch agent/run-{id}-{slug}.
- Always call rag_search before planning or editing (unless RAG is OFF for the run).
- Always finish() with a structured summary: changed files, risks, tests, docs updated.
- On error, do not auto-rollback. Let the user choose.

git-workflow.mdc

---
description: Git rules.
alwaysApply: true
---

# Git

- Branch per run: agent/run-{run_id}-{short-slug}.
- Default branch is never modified by an agent.
- No automatic push. Push requires user approval AND token ability git:push AND safety.auto_git_push=true.
- Force pushes are hard-blocked.
- Conflicts: abort and pause the run for user resolution.
- Repository URLs allowed only from approved hosts (github.com, gitlab.com, bitbucket.org).

testing.mdc

---
description: Testing rules.
alwaysApply: true
---

# Testing

- Pest + PHPUnit for backend.
- Every public service method has at least one test.
- Every route handler has at least one feature test.
- New migrations: a test that boots, migrates, asserts schema, then `migrate:rollback`.
- RAG tests use the deterministic mock embedding client.
- iPhone: Swift Testing for view models; UI tests for critical flows (login, start run, view console).

security.mdc

---
description: Security rules.
alwaysApply: true
---

# Security

- No secrets in logs, Git, docs, or responses. Mask everywhere (sk-…XXXX).
- Command allowlist + blocklist enforced via CommandExecutionService.
- Workspaces are isolated under workspace.root; path traversal is rejected.
- Validate repository URLs (scheme, host, no credentials).
- Rate-limit API endpoints (60 req/min default, 6 req/min for run-start).
- Audit log all critical actions in agent_events.
- Snapshot before risky change. Manual approval before push/deploy.
- Role-based permissions via Sanctum abilities.

iphone-first.mdc

---
description: iPhone-first API rules.
alwaysApply: true
---

# iPhone First

- All endpoints support pagination (cursor or page).
- Live data uses SSE: GET /api/runs/{run}/events/stream.
- Diffs are server-rendered as unified diff strings; do not require client-side computation.
- Responses use camelCase JSON keys (configured in API resources).
- Error responses use RFC 7807 (application/problem+json).
- File payloads support range requests for large logs.
- Avoid chatty endpoints: one call per screen ideally.

documentation-auto-update.mdc

---
description: Documentation auto-update rules.
alwaysApply: true
---

# Documentation Auto-Update

- Update PROJECT_MAP.md, DATABASE_SCHEMA.md, ARCHITECTURE_DIAGRAMS.md, API_ENDPOINTS.md, CHANGELOG_AI.md after every completed run that changes code.
- Only edit content inside <!-- AUTO-GENERATED:START --> ... <!-- AUTO-GENERATED:END --> blocks.
- Mirror canonical docs into .cursor/rules/project-overview.mdc and .claude/PROJECT_CONTEXT.md.
- Strip secrets before write.
- Validate Mermaid blocks before writing.
- Doc updates run on the `docs` Horizon queue and do not block the run orchestrator.