cursor-implements

Base Cursor “implements” repo for agentic coding workflows.

Chinese docs: README.zh-CN.md.

Kit version: see VERSION / CHANGELOG.md. Agent entrypoint: AGENTS.md.

Quickstart: copy .cursor/ into a new project

# copy into target project (creates target dir if missing)
scripts/copy-cursor.sh /path/to/target-project

# overwrite target .cursor/
scripts/copy-cursor.sh /path/to/target-project --force

# merge into existing .cursor/ (overwrite overlapping files)
scripts/copy-cursor.sh /path/to/target-project --merge

# skip Go fmt pre-commit hook (non-Go projects)
scripts/copy-cursor.sh /path/to/target-project --force --skip-go-fmt

# preview only
scripts/copy-cursor.sh /path/to/target-project --dry-run

Also copies AGENTS.md, VERSION, CHANGELOG.md, and templates/ when present.

Cursor Rules (Roles)

This repo ships role rules under .cursor/rules/ to standardize plan → implement → verify.

Core

• workflow-bootstrap (alwaysApply): short pointer to AGENTS.md and the mainline.
• orchestrator: role chaining / copy-paste prompt library (planner→implement→verify→PR).
• planner: turn requirements into an executable IMPLEMENTATION_PLAN.md (steps, acceptance criteria, risks, rollback, test plan). No code changes before ACT.
• implementer: convert IMPLEMENTATION_PLAN.md into high-quality code after ACT, with minimal changes, tests, and objective acceptance checks.
• verifier: validate implementation against plan and evidence; outputs Pass/Fail/Blocked with gaps and next actions.
• debugger: evidence-driven root-cause analysis and minimal fix strategy with reproducible verification.
• test-runner: run the smallest sufficient test set, summarize results, and map failures back to changes.
• security-auditor: lightweight security audit (auth, input validation, secrets, dependency risk) with actionable fixes.
• code-reviewer: high-signal review focused on correctness, contracts, security, performance, maintainability, and plan alignment.

Delivery & release

• pr-author: produce high-quality PR title/body (summary, test plan, risks, rollback, screenshots/demos).
• release-manager: rollout/migration/flags/monitoring/rollback guidance to ship safely.

Structure

• refactorer: behavior-preserving refactors with guardrail tests, small steps, and rollback points.

Frontend / backend slots

• frontend-engineer: frontend delivery focusing on a11y, performance, consistency, and verifiable UI acceptance.
• backend-engineer: backend delivery focusing on API contracts, auth, idempotency, reliability, and observability.
• api-designer: stable, evolvable API specs with examples, compatibility and migration strategy.
• ux-reviewer: usability and interaction review with actionable improvements and validation steps.
• qa: manual test cases + regression checklist covering risks, edges, and reproducible expectations.

See AGENTS.md for a short RACI between overlapping roles.

Suggested Workflow

1. Use planner to produce IMPLEMENTATION_PLAN.md (template: templates/IMPLEMENTATION_PLAN.md).
2. Say ACT to allow implementer to start coding.
3. As needed, use api-designer / frontend-engineer / backend-engineer during implementation to keep contracts and UX consistent.
4. Use test-runner, qa, code-reviewer, security-auditor, and verifier to validate before shipping.
5. Use release-manager for rollout/migrations/flags/monitoring and pr-author to finalize PR content.

Cursor Skills

Project skills live under .cursor/skills/ and travel with scripts/copy-cursor.sh.

Skill	Path	When to use
git-commit	.cursor/skills/git-commit/	Conventional commits: analyze diff, stage intelligently, write the message. Triggered by “commit these changes” / “commit code” / “提交代码” (also via Commit Skill Injector hook).
create-pr	.cursor/skills/create-pr/	Open a GitHub PR with gh (push if needed, pr-author-style body).
shitcode-scan	.cursor/skills/shitcode-scan/	Quantify tech debt / code smells (8 dimensions + worst files/functions with path:line).

# Example: scan a repo for tech debt (run from the skill directory, or pass the script path)
python3 .cursor/skills/shitcode-scan/scripts/shitcode_scorer.py /path/to/repo --top 15

Cursor Hooks (Workflow gates & reminders)

This repo includes project-level hooks in .cursor/hooks.json to make the workflow more “pipeline-like”.

• Plan Gate (preToolUse on Write|StrReplace|Delete): if there is no IMPLEMENTATION_PLAN.md, edits to non-doc/non-cursor files will ask for confirmation (nudges planner-first). Markdown/docs//templates/ are allowlisted.
• Step Checkpoint (postToolUse / afterFileEdit): when a plan exists, reminds to capture acceptance evidence + rollback notes + run minimal tests.
• Shell Safety (beforeShellExecution on risky commands): asks confirmation for destructive/state-changing commands (e.g. rm -rf, git reset --hard, force push, dependency installs) with severity hints.
• Go Fmt Pre-Commit (beforeShellExecution on git commit, optional): if staged *.go files are not gofmt-clean, runs gofmt -w, re-stages them, then allows the commit; denies if gofmt is missing or fails. Skip with copy-cursor.sh --skip-go-fmt.
• Secrets Pre-Commit (beforeShellExecution on git commit): denies commit if staged files look like .env / keys / credential JSON.
• Session Start (sessionStart): prints a short workflow quickstart.
• Commit Skill Injector (beforeSubmitPrompt): when the user asks to commit code (including Chinese “提交代码”), injects guidance to follow .cursor/skills/git-commit/SKILL.md.
• ACT Plan Detector (beforeSubmitPrompt): if the user says ACT without a plan, injects planner guidance.
• Verifier Stop Nudge (stop): when a plan exists, reminds to run verifier before finishing.

Notes:

• Hooks are designed to be lightweight and mostly non-blocking (ask-to-proceed), except quality gates (Go fmt / secrets) that may deny.
• Hook scripts live in .cursor/hooks/*.py.
• Go fmt hook requires gofmt on PATH (Go toolchain); omit for non-Go projects via --skip-go-fmt.

Role Orchestration (How to chain roles)

Treat IMPLEMENTATION_PLAN.md as the single “work order”. Most roles either produce it, execute it, or verify against it. Prefer the orchestrator rule for ready-made prompt templates.

Default mainline (most common)

• planner → produce IMPLEMENTATION_PLAN.md (steps/acceptance/risks/rollback/test plan)
• You say ACT
• implementer → implement step-by-step (each step is verifiable + rollbackable)
• test-runner → run minimal sufficient tests; map failures back to changes
• code-reviewer → correctness/contracts/risk review
• security-auditor → auth/input/secrets/dependency risk checks
• verifier → acceptance verdict: Pass / Fail / Blocked (with evidence)
• pr-author → PR title/body (summary, test plan, risks, rollback, screenshots/demos)
• release-manager → rollout/migration/flags/monitoring/rollback notes (when shipping)

Frontend / backend “slots”

• API-sensitive changes: api-designer → (update plan if needed) → backend-engineer / frontend-engineer
• UX-sensitive changes: ux-reviewer can run before implementation (pre-check) and after (post-check)
• More manual coverage: qa turns acceptance + risks into a regression checklist (pairs well with test-runner)

When things break (debug branch)

debugger (repro → evidence → root cause → minimal fix → verification) → back to test-runner → verifier.

Refactor branch

refactorer (guardrails first → small refactor steps → continuous verification) → test-runner / code-reviewer / verifier.

Copy-paste prompts

• “Use planner to produce IMPLEMENTATION_PLAN.md, then wait for me to say ACT.”
• “ACT: follow the plan from Step 1; after each step, provide acceptance evidence and rollback notes.”
• “Run test-runner, map failures to specific changes, and propose the smallest fix.”
• “Use verifier to verdict Pass/Fail/Blocked against acceptance criteria, with evidence.”
• “Use pr-author to draft the PR title/body; if shipping, use release-manager for rollout/rollback.”
• “Commit these changes” → follow git-commit skill.
• “Open a PR for this branch” → follow create-pr skill.
• “Scan this repo for tech debt / which files should we refactor first?” → follow shitcode-scan skill.

Tests / CI

python3 -m unittest discover -s tests -v
bash scripts/copy-cursor.sh /tmp/demo --dry-run

GitHub Actions: pylint on .cursor/hooks/, plus kit smoke (hooks tests + copy script).