Cursor Playbook

Prepare Cursor for the toolkit

1. Open the repository in Cursor, confirm AI-toolkit/ is visible in the file tree, and grant the assistant access to that folder.
2. Copy required agents/prompts/commands into .claude/ so Cursor and Claude point to the same files.
3. Pin claude.md, your session summary log, and your most-used agent/prompt files to the left sidebar for one-click referencing.
4. Run /init (or your stored “boot” snippet) so the assistant reads the current session, plan, and guardrails.
5. Install Cursor extensions you rely on (Git UI, testing panels, design previews) to complement the AI-driven workflow.

Cursor supports multiple projects—keep a dedicated “AI Toolkit” workspace open so you can drag plans/agents into any active repo.

File placement & context sync

• Agents: Keep canonical versions in AI-toolkit/agents/. Pin copies in the sidebar and toggle read-only to avoid unintentional edits.
• Prompts: Store essential prompts in .claude/prompts/ and leave the rest in the toolkit. Cursor can reference either location with @../AI-toolkit/prompts/name.md.
• Sessions: Open .claude/sessions/current.log in a split panel so you can paste updates without leaving Cursor.
• Scratch space: Maintain notes/cursor-scratch.md for command output, partial diffs, or brainstorming before updating Claude.

Working with agents inside Cursor

Prompt-driven development

Coordinate multi-agent runs

1. Map the chain: Run @plan_feature.md followed by tech-lead-orchestrator.md so the chat contains a sequenced agent plan with expected deliverables.
2. Confirm roles: Feed that plan into @team-configurator.md to lock in ownership, escalation rules, and success criteria; pin the output for quick reference.
3. Drive the sequence: Before invoking each specialist, paste the prior agent’s summary (or handoff note) so Cursor keeps the entire context in-line.
4. Agent-controlled delegation: When an agent needs to brief the next, ask it to run @session-closer.md (or generate a handoff paragraph) that lists TODOs, blockers, and artefacts for the successor.
5. Quality sweep: After the chain finishes, run @reliability-commander.md, @testing-expert.md, and @brutal-critic.md; record the results in /project:session-update before committing code.

Maintain an “agent stack” snippet in the thread so new contributors know which agent ran last and who is next in line.

Sample scenario: implementing a feature flag rollout

1. Prompt the brief: Start a new chat thread, run @create_brief.md to capture business goals, then @plan_feature.md to outline backend + frontend steps. Copy the outputs into the Claude session log.
2. Multi-agent plan: Invoke tech-lead-orchestrator.md to define the sequence (backend-developer → react-component-architect → testing-expert) and lock assignments with @team-configurator.md.
3. Execution in Cursor: Call @backend-developer.md to add flag evaluation code, run recommended tests in the terminal, then switch threads and use @react-component-architect.md for UI toggles. Each agent emits a handoff note via @session-closer.md.
4. Session tracking: After each milestone, paste terminal output plus the agent handoff into /project:session-update so Claude, Gemini, and Codex stay in sync.
5. Review & release: Conclude with @code_review.md, @testing-expert.md, and @write_docs.md. Export the Cursor transcript and attach it to your session insights archive.

Use the Git panel to stage only the files mentioned in each agent handoff—this keeps diffs small and matches the orchestrator’s plan.

Full multi-agent example (Cursor)

This walkthrough shows every chat message, agent invocation, and session update needed to deliver a “payment receipt email” feature entirely within Cursor.

1. Open a fresh thread and send:
   Command + Enter → @create_brief.md
// paste ticket description + stakeholders
2. Generate the build plan:
   @plan_feature.md
// include acceptance criteria + file list
3. Draft orchestration:
   @tech-lead-orchestrator.md
// ask for ordered phases + recommended agents + artefacts
4. Lock ownership:
   @team-configurator.md
// “Backend: Alice, Frontend: Bob, QA: Chen. Escalate to Dana.”
5. Backend agent run:
   @backend-developer.md
// provide orchestrator phase 1 summary
   Cursor returns patch instructions. Apply edits, run tests:
   npm run test:backend
   Paste command output back into chat.
6. Agent-controlled handoff: ask Cursor “Summarise the backend changes as a handoff note” or run:
   @session-closer.md
   Keep the generated note open.
7. Frontend agent run: Start a new message:
   @react-component-architect.md
// include handoff note + relevant file list
   Follow the returned instructions, run frontend tests:
   npm run test:ui
   Paste logs into chat.
8. Quality sweep via agents:
   @testing-expert.md
// request additional coverage ideas
@brutal-critic.md
// supply git diff for qualitative review
9. Documentation prompt:
   @write_docs.md
// feed plan output + testing results + git log
10. Session logging: copy the latest Claude log into Cursor, request “Summarise today’s work”, then paste the summary, command outputs, and agent URLs into /project:session-update within Claude.
11. Finalise: trigger /project:session-end in Claude, attach the exported Cursor transcript, and stage/commit using Cursor’s Git panel.

Keep each chat message prefixed with // comments to indicate context (plan, handoff, logs). This makes the transcript self-documenting when you archive it.

Workflow patterns

1. Kickoff: Import the latest Claude session, run @plan_feature.md, and pin the plan to the top of the chat.
2. Implementation: Use Cursor’s inline edit suggestions plus the terminal to run tests/formatters. Stage changes with the Git panel.
3. Legacy work: Ask Cursor to summarise history using session-restorer.md, then follow code-refactorer.md for safe sequencing.
4. Frontend & design: Combine frontend-designer.md with live preview (Storybook/Vite) to tighten the design loop.
5. Wrap-up: Paste results into /project:session-update, generate docs, and trigger session-closer.md.

Discipline-specific tips

• Backend: Pair Cursor’s multi-file edit feature with django-backend-expert.md or fastapi-expert.md to scaffold endpoints rapidly.
• Frontend: Use react-component-architect.md to draft component structures, then let Cursor refactor JSX/TSX inline.
• DevOps: Feed logs or pipeline output to reliability-commander.md and apply the fixes directly within the same workspace.
• Design & content: Combine frontend-designer.md, vibe-coding-coach.md, and Cursor’s Markdown preview to iterate on UX copy.

Mirror session logs

1. Copy the latest /project:session-update from Claude and paste it into Cursor for shared context.
2. After Cursor suggests changes, update the Claude log with decisions, command outputs, and next steps.
3. Archive significant Cursor chats in your session insights folder or ticketing system for future reference.

Keep a dedicated “Cursor summary” section in each session log so teammates know what was accomplished in the IDE.

Integrations and tools

• Terminal commands: Run pytest, npm test, go test, docker compose up in the built-in terminal, then share results with the assistant.
• Git UI: Use Cursor’s diff viewer to inspect patches from agents before committing.
• Testing & linting: Configure tasks for eslint, ruff, prettier, black, and share outputs for remediation.
• Design integrations: Link Storybook, Figma, or Chromatic previews so Cursor and agents have visual context.
• External tools: Combine Cursor with CLIs like httpie, kubectl, or terraform when executing infrastructure tasks.

Best practices

• Always keep Claude as the source of truth—after Cursor sessions, paste summaries into /project:session-update.
• Work in focused threads (one per feature/bug) so history stays searchable and scoped.
• Hide or collapse irrelevant files in the sidebar to keep the assistant focused on the files you are editing.
• Use Cursor’s inline “Accept suggestion” feature judiciously—skim diffs before staging to avoid subtle regressions.
• Pair with other tools (Gemini, Codex, OpenCode) by sharing plan outputs and session logs regularly.