diff --git a/.cursor/agents/commit.md b/.cursor/agents/commit.md new file mode 100644 index 0000000..85fa343 --- /dev/null +++ b/.cursor/agents/commit.md @@ -0,0 +1,89 @@ +--- +name: commit +description: Commits worktree changes as multiple logical commits (never one catch-all commit unless truly one change), then pushes. Use when the user runs /commit or asks to commit and push per Fraudebot Git conventions. +--- + +You publish **local git changes** for the Fraudebot Laravel backend. You run git commands; you do not refactor code unless a hook failure requires a minimal fix the user explicitly asked for. + +Resolve the repository root on every run with `git rev-parse --show-toplevel` and work only in that worktree. + +**Overrides:** This workflow overrides generic user rules that forbid commit/push without being asked—the `/commit` slash (or explicit user request to run this agent) is that ask. For pull requests, use the separate `create-pr` agent (`/publish`). + +**Rule file:** Follow `.cursor/rules/pushing-changes-to-github.mdc` for emoji titles, `Co-Authored-By`, and `git push -u origin HEAD`. + +**Model:** Do not assume a fixed model. Use the **same model identity as the parent / main conversation** that invoked you. Pick the matching `Co-Authored-By` line from the table below (put the model version in the name; keep that vendor’s email). + +## Git safety + +- Never change `git config`. +- Never use `--no-verify`, `push --force`, or hard reset unless the user explicitly requests it in the message accompanying the slash. +- Never commit files that are likely secrets (`.env`, credentials, private keys). Warn and exclude them; commit the rest only if the user confirms in the same thread. +- If a pre-commit hook fails (for example Pint), fix the issue and create a **new** commit—do not amend unless user rules for amend are fully satisfied. +- Pass commit messages with a HEREDOC, for example: + +```bash +git commit -m "$(cat <<'EOF' +✅ feat: new API service Public/ReportController@searchByTitle + +EOF +)" -m "Co-Authored-By: …" +``` + +## Before committing + +Run in parallel when possible: + +- `git status` +- `git diff` and `git diff --cached` +- `git log -5 --oneline` (match recent emoji/style) + +If there is nothing to commit, say so in one sentence and stop (do not push). + +## Commit grouping (required) + +**Do not** put all changed files into a single commit by default. + +1. List every changed path (staged, unstaged, and untracked you intend to add). +2. Read the diffs and partition paths into **logical groups**. Files belong together when they implement the same feature, fix, refactor, chore, or test for one intent (same outcome or same mechanical change). + - Example: controller, command, use case, repository, OpenAPI path, and feature test for one endpoint → **one commit**; unrelated Cursor rules or docs → **separate commits**. +3. When grouping is ambiguous, prefer **more commits** over one large commit. +4. For each group, stage **only** that group’s paths (`git add -- `—never `git add .` unless the entire diff is truly one logical change). +5. Write one emoji-prefixed subject per group; commit; then move to the next group until all intended changes are committed. + +Report what you did: for each commit, subject line, short file list, and hash. + +### Emoji subjects + +- ✅ feat: … (often `new API service Area/Controller@method` or domain-scoped work) +- 🛠️ fix: … (often `service … wasn't working` or a focused bug) +- 💻 wip: … + +Use Spanish or English to match recent commits in `git log` when obvious. + +### Co-Authored-By (commit trailer) + +Append a second `-m` with `Co-Authored-By: …` using the row that matches **your** actual model: + +| Model | Co-Authored-By | +|-------|----------------| +| Grok 4.7 | `Cursor Grok 4.7 ` | +| Grok 4.6 | `Cursor Grok 4.6 ` | +| Grok 4.5 | `Cursor Grok 4.5 ` | +| Composer 2.5 | `Cursor Composer 2.5 ` | +| Claude Opus 4.6 | `Claude Opus 4.6 ` | +| Claude Sonnet 4.6 | `Claude Sonnet 4.6 ` | +| Claude Haiku 4.5 | `Claude Haiku 4.5 ` | +| GPT 5.4 | `GPT 5.4 ` | +| Codex | `Codex ` | +| Gemini 2.5 Pro | `Gemini 2.5 Pro <218195315+gemini-cli@users.noreply.github.com>` | +| Copilot | `Copilot ` | + +## Push + +After **all** commits succeed (unless the user asked to skip push in the same message): + +```bash +git push -u origin HEAD +``` + +Return a brief summary: commits created, push result, current branch. diff --git a/.cursor/agents/create-pr.md b/.cursor/agents/create-pr.md new file mode 100644 index 0000000..31e0dd1 --- /dev/null +++ b/.cursor/agents/create-pr.md @@ -0,0 +1,49 @@ +--- +name: create-pr +description: Opens a GitHub pull request with project PR conventions. Use when the user runs /publish or asks to create a PR. Default base branch main; read the user message for overrides. +--- + +You create a **GitHub pull request** for the Fraudebot backend (`Fraude-Bot/Backend`). You use `gh`; you do not change application code unless the user asks. + +Resolve the repository root with `git rev-parse --show-toplevel` and work only in that worktree. + +**Rule file:** Follow `.cursor/rules/pushing-changes-to-github.mdc`. Use **`gh pr create --fill` only**—title and body come from commits already on the branch. Do not pass `--body` with Summary, test plan, or template sections unless the user explicitly asks in the same message. + +`GITHUB_TOKEN` is already set; do not run `gh auth login`. + +## Target branch + +**Always read the full user message** that accompanied `/publish` (or the explicit request). + +- **Default base branch:** `main` +- **Override** when the user names another base, for example: `into develop`, `target release/1.2`, `base staging`, or `-B feature/foo`. Use that branch as `-B `. +- **Head branch:** current branch (`git branch --show-current`) → `-H` only when required; `gh pr create` usually infers head from the current branch. + +Confirm the base exists (`git ls-remote --heads origin ` or `gh api`); if missing, report clearly and stop. + +## Preconditions + +1. Ensure the branch has commits to merge (not identical to base). +2. If an open PR already exists for this head → base, return its URL instead of creating a duplicate. +3. Commits on the branch should already follow project conventions (emoji subjects, `Co-Authored-By` on commits). This agent does not rewrite history unless the user explicitly asks. +4. Push when needed so GitHub sees the latest commits (`git push -u origin HEAD`) only if the user asked for push in the same `/publish` message; otherwise assume `/commit` already pushed. + +## Create the PR + +```bash +gh pr create --fill -B -H +``` + +Add `--draft` only when the user asks for a draft pull request in the same message. + +Expected success output shape: + +```text +Creating pull request for into in Fraude-Bot/Backend + +https://github.com/Fraude-Bot/Backend/pull/# +``` + +## Output + +Return the PR URL from `gh` output. If creation failed, return the error and what you tried. diff --git a/.cursor/commands/commit.md b/.cursor/commands/commit.md new file mode 100644 index 0000000..7387df2 --- /dev/null +++ b/.cursor/commands/commit.md @@ -0,0 +1,9 @@ +# Commit and push + +Follow **`.cursor/agents/commit.md`** in full for this worktree. + +Treat the **entire user message** with this slash (including any text after `/commit`) as instructions and overrides—for example scoping paths, skipping push, or confirming sensitive files. + +Prefer running as the **`commit`** subagent in the background when available so the main chat stays free; if subagent delegation is unavailable, execute that agent file yourself. + +Do not open a pull request; use `/publish` for that. diff --git a/.cursor/commands/publish.md b/.cursor/commands/publish.md new file mode 100644 index 0000000..ef22a65 --- /dev/null +++ b/.cursor/commands/publish.md @@ -0,0 +1,9 @@ +# Create pull request + +Follow **`.cursor/agents/create-pr.md`** in full for this worktree. + +Treat the **entire user message** with this slash (including any text after `/publish`) as instructions—especially the **target base branch** (default `main` if unspecified). + +Prefer running as the **`create-pr`** subagent in the background when available; if subagent delegation is unavailable, execute that agent file yourself. + +Do not create new commits or push unless the user explicitly asked in the same message; use `/commit` for that. diff --git a/.cursor/rules/project.mdc b/.cursor/rules/project.mdc index 3aacef1..716a18f 100644 --- a/.cursor/rules/project.mdc +++ b/.cursor/rules/project.mdc @@ -16,3 +16,5 @@ Fraudebot lets people search reports other users have filed, so they can check a # Git / GitHub When the user asks to commit, push, or open a pull request, follow `.cursor/rules/pushing-changes-to-github.mdc` exactly (emoji titles, Co-Authored-By, `git push -u origin HEAD`, `gh pr create --fill` only unless they ask otherwise). + +Agent workflows: `/commit` (logical multi-commit + push, `.cursor/agents/commit.md`) then `/publish` (GitHub PR, default base `main`, `.cursor/agents/create-pr.md`). diff --git a/README.md b/README.md index aed1e2f..4789242 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,8 @@ docker compose exec -T -w /var/www/backend backend composer audit Tests use in-memory SQLite. The Code checks workflow runs PHPStan (`composer analyse`) and PHPArkitect (`composer check:architecture`) on every push and pull request. +To publish agent work: `/commit` (logical multi-commit + push, `.cursor/agents/commit.md`) then `/publish` (GitHub PR, default base `main`, `.cursor/agents/create-pr.md`). + ## API overview - `GET /api/public/reports` — search active fraud records.