Skip to content

Commit 2ad736b

Browse files
northdpolecursoragent
northdpole
and
cursoragent
committed
Add shared Cursor agent instructions for OpenCRE.
Track AGENTS.md and .cursor/rules so the team shares human-plan-then-agent-execute workflows, CI/PR policies, and domain safety guardrails. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 2e428cd commit 2ad736b

6 files changed

Lines changed: 147 additions & 1 deletion

File tree

‎.cursor/rules/alembic-deploy-guardrail.mdc‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
description: Enforce Alembic DB-revision guardrail before deploy/migration operations
3+
alwaysApply: true
4+
---
5+
6+
# Alembic Deploy Guardrail
7+
8+
- Before any production/staging deploy or migration operation, run the Alembic guardrail check:
9+
- `python scripts/check_alembic_revision_guardrail.py`
10+
- or `make alembic-guardrail`
11+
- If the guardrail reports unknown DB revision(s), stop immediately and do not run migrations until lineage is reconciled.
12+
- For Heroku deploys, keep `Procfile` `release:` wired to the guardrail so incompatible slugs fail before web/worker rollout.
13+
- After backup restore operations, re-run the guardrail before any `flask db upgrade`.
14+

‎.cursor/rules/autonomous-workflow.mdc‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
description: Autonomous execution defaults for OpenCRE
3+
alwaysApply: true
4+
---
5+
6+
# OpenCRE Autonomous Workflow
7+
8+
Policy (CI/PR, git, validation order, critical paths): see `AGENTS.md`.
9+
10+
- For big changes, wait for human plan approval (`multi-agent-workflow.mdc` Phase 1) before editing.
11+
- After plan approval, execute tasks end-to-end unless blocked by auth/secrets, destructive actions, or material plan deviations.
12+
- Prefer small, safe changes and avoid unrelated refactors.
13+
- Use `Makefile` targets when possible.
14+
- For substantive code changes, run `make lint`, `make mypy`, and `make test` before handoff (skip only when clearly irrelevant and explain why).
15+
- If any check reports failures introduced by your changes, fix them before handoff.
16+
- If commit verification depends on shell initialization, run verification commands in a zsh-compatible shell context so environment-dependent checks are not skipped.
17+
- Run long commands in the background and monitor until completion.
18+
- Do NOT commit or push unless explicitly asked (except when the user explicitly requests CI auto-fix / PR creation; see `AGENTS.md`).
19+
- In commits do not add "made with cursor" lines.
20+
- At handoff, report: changed files, checks run, and any residual risks.

‎.cursor/rules/multi-agent-workflow.mdc‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
description: Human plans big changes first; agent executes after explicit approval
3+
alwaysApply: true
4+
---
5+
6+
# Multi-Agent Workflow (Human Plan → Agent Execute)
7+
8+
For **big changes**, split work into two phases. Do not skip Phase 1.
9+
10+
## What Counts as a Big Change
11+
12+
Treat the change as **big** when any of these apply:
13+
14+
- New feature, new standard importer, or new user-facing capability
15+
- Expected to touch **3+ files** or **>500 lines** of diff
16+
- Refactor or migration with behavioral risk
17+
- Touches critical paths (auth, secrets, production data, payments)
18+
- Requirements are incomplete or have meaningful product/design choices
19+
20+
Small fixes (single-file bugfix, typo, test-only tweak, clear one-liner scope) skip this rule; use `plan-first-workflow.mdc` only.
21+
22+
## Phase 1 — Human-Led Planning (Agent Facilitates, No Code)
23+
24+
**Stop before editing.** Your job is to help the human produce and approve a plan.
25+
26+
1. **Acknowledge** this is a big change and that planning comes first.
27+
2. **Ask the human** the minimum questions needed to plan well. Prefer a short numbered list over a long questionnaire. Typical prompts:
28+
- What is the goal and definition of done?
29+
- What source format / data / URLs does FOOBAR (or the feature) use?
30+
- Which existing pattern should we mirror (e.g. a similar importer or route)?
31+
- Acceptance criteria and manual checks?
32+
- Out of scope / constraints?
33+
3. **Draft a plan** for the human to edit, including:
34+
- Goal and acceptance criteria
35+
- Steps in execution order
36+
- Files likely touched (with `@`-style paths where helpful)
37+
- Similar code to follow
38+
- Test and validation plan (`make lint`, `make mypy`, `make test`, import smoke if relevant)
39+
- Risks and open questions
40+
4. **Wait for explicit approval** before Phase 2. Approval looks like: "looks good", "proceed", "approved", or an edited plan the human confirms.
41+
5. **Do not** create commits, push, or write implementation code during Phase 1. Research and read-only exploration are fine.
42+
43+
If the human already supplied a complete plan, reflect it back briefly and ask them to confirm before executing.
44+
45+
## Phase 2 — Agent Execution (Autonomous)
46+
47+
After the human approves the plan:
48+
49+
1. **Execute end-to-end** per `autonomous-workflow.mdc` and `AGENTS.md`.
50+
2. **Follow the approved plan**; if you discover a material deviation, pause and ask before continuing.
51+
3. **Implement in small increments** when possible; run validation as you go.
52+
4. **Evaluate** against acceptance criteria: run tests, note manual spot-checks for the human.
53+
5. **Hand off** with the standard checklist (changes, checks, CI status, risks).
54+
55+
## Optional Cursor Agent Window Roles
56+
57+
When using parallel agents, map roles to phases:
58+
59+
| Role | Phase | Responsibility |
60+
|------|-------|----------------|
61+
| Planner | 1 | Expand prompt into spec + acceptance criteria; human approves |
62+
| Builder | 2 | Implement approved plan |
63+
| Evaluator | 2 | Run tests/checks; compare results to acceptance criteria |
64+
65+
One agent can cover Builder + Evaluator; Phase 1 still requires human approval before Builder starts.

‎.cursor/rules/plan-first-workflow.mdc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
description: Plan with reasoning before substantive code changes
3+
alwaysApply: true
4+
---
5+
6+
# Plan-First Workflow
7+
8+
Apply before making non-trivial edits that are **not** big enough to trigger `multi-agent-workflow.mdc`.
9+
10+
If the change is big (new feature/importer, 3+ files, >500 lines, critical paths), use the human-plan → agent-execute flow there instead of planning and coding in one step.
11+
12+
## Before Editing
13+
14+
- Provide a brief plan with reasoning: goal, steps, files likely touched, and validation approach.
15+
- Break the problem into smaller steps and think through each separately.
16+
- If intent is ambiguous, ask before implementing.
17+
- Check `docs/runbooks/` when the change touches deploy, DB, imports, or ops workflows.
18+
19+
## While Editing
20+
21+
- Only modify code directly relevant to the request.
22+
- Never replace code with placeholders (e.g. `// ... rest of the processing ...`). Include complete, working code.
23+
- Prefer referencing existing patterns with file paths (e.g. "similar to `application/web/web_main.py` route handlers") over inventing new conventions.
24+
- When debugging, state observations first, then reasoning, then the proposed fix.
25+
26+
## After Editing
27+
28+
- Before handoff, briefly explain key design choices so a reviewer can ask "why this way?" without re-reading the whole diff.
29+
- Prefer small, reviewable diffs; validate incrementally when possible.

‎.cursor/rules/production-db-ops-safety.mdc‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
description: Require all-caps confirmation for destructive production DB operations and prefer pre-op backups
3+
alwaysApply: true
4+
---
5+
6+
# Production DB Operations Safety
7+
8+
- For production database operations, treat destructive actions (`DELETE`, `DROP`, `TRUNCATE`, irreversible `ALTER`) as high risk.
9+
- Prefer using `scripts/db/` operations instead of ad-hoc production DB commands whenever those scripts cover the use case.
10+
- Before proposing or executing destructive production DB actions, require explicit all-caps confirmation from the user.
11+
- Confirmation should be exact and unambiguous (for OpenCRE scripts: `I_UNDERSTAND_OPENCREORG_PROD_DB_DESTRUCTIVE_ACTION`).
12+
- Prefer capturing a fresh backup before destructive production DB actions; if a backup is skipped, clearly explain risk and ask for confirmation again.
13+
- If app/environment target is ambiguous, stop and ask to confirm target app first.
14+

‎.gitignore‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,9 @@ v/
4646
.venv/
4747

4848
### Local AI/editor workspaces ###
49-
.cursor/
49+
.cursor/*
50+
!.cursor/rules/
51+
!.cursor/rules/**
5052
.claude/
5153

5254
### Frontend
@@ -79,3 +81,5 @@ tmp/
7981

8082
### CREs dir
8183
cres/*
84+
### Local project management tooling
85+
project management scripts/

0 commit comments

Comments
 (0)