bergamota-kit

A curated collection of skills for deliberate planning, rigorous debugging, and disciplined execution in Cursor agent workflows.

Homepage Source

skills planning subagent research debugging prompt-engineering workflow orchestration uiux npm

9 skills

debugger

--- name: debugger description: Systematic debugging workflow for code analysis, root cause investigation, and solution validation. Use when debugging errors, investigating bugs, analyzing stack tra

---
name: debugger
description: Systematic debugging workflow for code analysis, root cause investigation, and solution validation. Use when debugging errors, investigating bugs, analyzing stack traces, fixing runtime issues, or troubleshooting code problems.
---

<context>
  <role>Systematic debugger. You analyze code and errors, identify root cause with evidence, implement minimal fixes, and validate. Use only: Edit, Delete, Shell, SemanticSearch, WebSearch, Grep, ListDir, Glob, Read.</role>
  <references>Apply .cursor/rules/cot.mdc (reasoning), .cursor/rules/quality-assurance.mdc (accuracy), .cursor/rules/coding.mdc (technical standards).</references>
  <inputs>User provides: error messages, stack traces, affected files, reproduction steps, and optionally runtime/framework context.</inputs>
</context>

<contract>
  <phases>
    <phase id="1" name="Context Analysis">Read all provided files and errors; search codebase for related components and usages; identify environment and framework; classify issue type (syntax, runtime, logic, performance, security). Validation: one-sentence problem with specific symptoms.</phase>
    <phase id="2" name="Delegate Instrumentation Setup to sub-agent">Invoke a `generalPurpose` subagent to add instrumentation logs in all files/places needed, thinking outside the box from the start. Consider all execution paths, edge cases, state transitions, API calls, data transformations, and error boundaries. The agent should strategically place logs to capture maximum diagnostic information without cluttering the codebase. Validation: instrumentation covers critical paths and provides sufficient visibility into the issue.</phase>
    <phase id="3" name="Root Cause Investigation">Document exact errors and reproduction steps; generate at least 2 hypotheses; gather evidence (source, docs, API); test and eliminate hypotheses. Validation: single root cause with code evidence (file paths, line numbers).</phase>
    <phase id="4" name="Solution Development">Design fix for root cause; assess impact and alternatives; choose solution by effectiveness, risk, maintainability. Validation: fix addresses root cause with minimal side effects.</phase>
    <phase id="5" name="Implementation and Validation">Implement only necessary changes; verify fix; check regressions and linting; document what was fixed and why. Validation: issue resolved, no new errors, lint passes.</phase>
  </phases>
  <skip_rules>Skip phase 1 and 2 if issue is trivial and context is clear. Skip phase 3 if root cause is obvious from error. Skip phase 4 if single obvious solution exists. Always complete phase 5. Document any skipped phase with justification.</skip_rules>
</contract>

<instructions>
  1. Execute phases in order unless skip_rules apply. For each phase, perform required actions then state validation.
  2. When information is missing: state "I don't have enough information to proceed. I need: [specific items]". Do not guess or fabricate code or APIs.
  3. When uncertain: state "I need to verify [claim] against [source: documentation/codebase]" and use search before proceeding.
  4. Cite sources: file paths and line numbers for code; official docs URLs for API claims. Format: "According to [source], [claim]."
  5. If root cause cannot be determined: document investigated paths, eliminated hypotheses, information gaps; ask user specific questions; do not implement speculative fixes.
  6. If solution fails: verify implementation, re-examine root cause, check contributing factors; document failure and revised approach.
</instructions>

<formatting>
  Output exactly four sections in this order:
  1. **Problem statement**: One-sentence summary; symptoms (errors, behavior, steps).
  2. **Analysis**: Root cause with code evidence (paths, lines); eliminated hypotheses; information gaps if any.
  3. **Solution**: Exact changes with file paths; rationale; impact and side effects.
  4. **Validation**: Steps to verify fix; regression checks; lint status.
  Use only data from codebase or user; no speculation. Bullets or short paragraphs per section.
</formatting>

horse-around

Coordinates multiple AI agents working in parallel on complex projects using file-based communication. Use when the user wants to coordinate parallel AI sessions,

---
name: horse-around
description: Coordinates multiple AI agents working in parallel on complex projects using file-based communication. Use when the user wants to coordinate parallel AI sessions, manage multi-chat workflows, set up task coordination systems, or when they mention "parallel AI", "swarm commander", "multiple chats", or "horsin around".
---

# Horse Around - Parallel AI Coordination

Coordinates multiple AI agents working in parallel using file-based communication.

## Core Principles

- Orchestrator coordinates only. Execution happens in parallel subagents.
- Launch ALL chat subagents simultaneously in parallel batch with `is_background: true`. Sequential launches prevent parallelism.
- Tasks exceeding estimate by 10% must STOP and alert.
- File-based communication through markdown files.
- Each subagent has one focused responsibility.

## Setup Workflow

1. Create coordination directories:
   - **PowerShell**: `New-Item -ItemType Directory -Force -Path coordination/orders,coordination/answers,coordination/questions,coordination/alerts,coordination/logs`
   - **Bash**: `mkdir -p coordination/{orders,answers,questions,alerts,logs}`
2. Create `coordination/COMMAND_CENTER.md` from `templates/COMMAND_CENTER_template.md`
3. Identify parallel tasks with no dependencies
4. Create order files: `coordination/orders/order_chat_[LETTER]_[ROUND].md` from `templates/order_template.md`
5. Launch ALL generalPurpose subagents in parallel batch with `is_background: true`

Order files require: mission, context, tasks with estimates, deliverables, time tracking, success criteria.

Subagent execution: read order file, track time, update every 15 minutes, stop if 10% over estimate, create answer file on completion.

## Parallel Launch Pattern

Launch ALL subagents simultaneously in the same parallel batch. Do not launch sequentially.

For each chat (Chat A, B, C, etc.), create one generalPurpose subagent configured to:
- Read the corresponding order file: `coordination/orders/order_chat_[LETTER]_[ROUND].md`
- Execute tasks independently with time tracking
- Create answer file on completion

Launch all subagents in a single parallel batch, one subagent per chat/task, all with `is_background: true`. Sequential launches prevent true parallelism.

## Time Management

Timeout threshold = estimate + 10%. If not 90% done by threshold, STOP and create alert.

Time tracking template:
```markdown
| Task | Estimated | Started | Actual | Status |
|------|-----------|---------|--------|--------|
| Task 1 | [X]m | | | Pending |
| Task 2 | [X]m | | | Pending |
| **Total** | **[X]m** | | | |
**Timeout threshold:** [Total + 10%] minutes
```

## File Types

- Orders: `orders/order_chat_[LETTER]_[ROUND].md` - Task assignments
- Answers: `answers/answer_chat_[LETTER]_[ROUND].md` - Results reporting
- Questions: `questions/question_[FROM]_to_[TO]_[N].md` - Inter-chat questions
- Alerts: `alerts/alert_[CHAT]_[TYPE].md` - Timeout/blocker notifications
- Command Center: `COMMAND_CENTER.md` - Master dashboard

## Templates

Available in `templates/`: `order_template.md`, `answer_template.md`, `COMMAND_CENTER_template.md`, `question_template.md`, `alert_template.md`

## Best Practices

Orchestrator: coordinate only, launch ALL subagents simultaneously in parallel batch with `is_background: true`, break into parallel tasks, check Command Center every 15 minutes, respond to blockers within 10 minutes.

Subagent: read entire order first, track time immediately, update every 15 minutes, follow 10% timeout rule, ask questions early, complete answer template.

## Common Patterns

- Handoff: Chat A creates artifact → Chat B uses in next round
- Mirror: Chat A builds → Chat B tests in parallel
- Specialist: Assign by expertise (backend/frontend/testing)

## Scaling

2-3 chats: simple coordination. 4-5 chats: optimal. 6+ chats: consider deputy commander.

light-prompt

Converts raw user input into a tight, structured prompt capped at about 200 tokens to reduce model drift. Use when the user wants a short, reusable prompt, asks to "light prompt" or compress a request, or when downstream calls need a minimal instruction block.

# Light prompt

<context>
  Turn the given input into a **single structured prompt** whose total length is **at most ~200 tokens** (approximate). Shorter is acceptable; exceeding the cap is not.

  Longer instructions increase off-task behavior. This skill trades elaboration for clarity and boundaries.
</context>

<instructions>
  **Technique (research-backed, compressed)**

  Effective short prompts combine:

  1. **Task** — one imperative sentence: what to produce.
  2. **Context** — minimal facts and **file references** using `@path` (e.g. `@folder/file`, `@src/component.vue`). List only paths the model must read.

  Omit sections that add no information. Be direct; avoid clever phrasing.

  **Token budget**

  - Treat **200 tokens** as a soft ceiling using judgment (roughly **120–180 English words** for many models; compress if longer).
  - If the source input is huge: **summarize intent** first, then apply this structure; do not paste long sources into the prompt unless the task is verbatim extraction.

  **Return**

  Return **only** the finished prompt text (no meta commentary), using the skeleton in `<example>` when it fits.

  Use shorter labels or merge lines if needed to stay under the cap.
</instructions>

<example>
Task: …

Context:
- @path/to/relevant/file
- @another/file
</example>

<formatting>
  **Quality check**

  Before returning:

  - [ ] Every line earns its tokens (no filler, no duplicate asks).
  - [ ] Task is unambiguous.
  - [ ] Context includes relevant `@file` paths when applicable.
  - [ ] Total length respects ~200 tokens.
</formatting>

npm-package-maintenance

# npm package maintenance

## Preconditions

- Run only in a git repository whose root contains `package.json` (npm package).
- Respect user and workspace rules: do not `git commit` or `git push` without explicit user permission unless the user has clearly authorized this full workflow in the same request.

## Workflow (order matters)

### 1. Uncommitted change review (gate)

Inspect working tree and index (`git status`, `git diff`, staged diff). Stop the workflow immediately and report to the user if any of the following appear:

- Build or test failures (run project checks if defined, e.g. `npm test`, `npm run lint`).
- Suspected secrets, credentials, or tokens in diff.
- Known-vulnerable dependency patterns in changed files (flag for `npm audit` follow-up).
- Changes that break stated project patterns (commit style, file layout, export surface, TypeScript/build config) when those patterns are documented or obvious from the repo.

Output a short verdict: **proceed** or **blocked** with reasons. If blocked, do not continue to steps 2–5.

### 2. Commits and versioning scope

If the gate passes:

- Group changes into separate commits by feature or concern (e.g. fix vs feat vs chore). Prefer [Conventional Commits](https://www.conventionalcommits.org/) when the repo already uses them.
- If multiple independent user-facing changes ship together, plan separate semver bumps or separate release branches only when the repo’s practice requires it; otherwise one release with one version bump is acceptable.

### 3. Changelog

If the repo has `CHANGELOG.md`, `CHANGELOG`, `History.md`, or package-specific changelog files under common locations, update every applicable file for the release:

- Add entries under the correct version section (or create the section after the version is chosen in step 4).
- Match existing format (Keep a Changelog, simple lists, etc.).

If there is no changelog, do not create one unless the user asks.

### 4. Version bump

- Read `package.json` `version` and any lockfile policy the repo uses.
- Decide bump using semver and the nature of commits: **patch** (fixes), **minor** (backward-compatible features), **major** (breaking changes). Align with repo tags and `npm version` usage if present.
- Update `package.json` version (and any other version fields the project maintains in sync). Run lockfile updates only if the project normally commits lock changes with releases.

### 5. Push

- After commits exist and the user has explicitly approved commit/push (or authorized this workflow): `git push` to the appropriate remote and branch. If the user has not approved, stop after preparing commits and list exact commands for them to run.

## Checklist

```
- [ ] Step 1: Review diffs; security and pattern check; gate pass/fail
- [ ] Step 2: Split into logical commit(s); align with versioning plan
- [ ] Step 3: Update existing changelog file(s)
- [ ] Step 4: Bump package version per semver
- [ ] Step 5: Push (only with permission) or hand off commands
```

## Notes

- Prefer `npm audit` for dependency risk when `package.json` / lockfiles changed materially.
- If the package is a monorepo workspace, apply the same steps per package or follow the repo’s release tool (changesets, lerna, etc.) when documented.

planning

Researches requirements when needed, then plans, organizes, and structures content without coding or implementation. Use when creating project plans, structuring work

---
name: planning
description: Researches requirements when needed, then plans, organizes, and structures content without coding or implementation. Use when creating project plans, structuring workflows, organizing tasks, building implementation roadmaps, or when planning features before execution.
---

<context>
  <role>Planning and Structuring Agent. Runs focused pre-plan research only when needed, then plans and structures content for parallel subagent execution. Does not execute, implement, or write application code.</role>
  <scope>
    Output: `.cursor/plans/{objective}.plan.md` only. No application code. Use SemanticSearch, Read, Grep, LS, Glob when analyzing codebase for planning.
  </scope>
  <constraints>
    Base all content on provided sources, conversation details, or verified references. No speculation. Plans must be structured so each todo is a self-contained unit delegatable to an independent subagent.
  </constraints>
</context>

<instructions>
  <item id="1" name="Elicit">
    <objective>Clarify objectives and ambiguities before writing the plan.</objective>
    <actions>
      <action>Ask targeted questions to resolve unclear goals, scope, and acceptance criteria.</action>
    </actions>
  </item>
  <item id="2" name="Research Gate">
    <objective>Decide if pre-plan research is required before building the plan.</objective>
    <condition>Run pre-plan research only if at least one trigger applies.</condition>
    <triggers>
      <trigger>Objective or acceptance criteria are ambiguous.</trigger>
      <trigger>Relevant files or modules are unknown.</trigger>
      <trigger>Task depends on unfamiliar architecture or integrations.</trigger>
      <trigger>Task likely spans 5 or more files or directories.</trigger>
    </triggers>
    <actions>
      <action>If required, delegate using the generalPurpose subagent.</action>
      <action>Synthesize findings into concrete plan inputs.</action>
    </actions>
  </item>
  <item id="3" name="isProject">
    <requirement>Set `isProject` to `true` always.</requirement>
  </item>
  <item id="4" name="Phases">
    <requirement>Break the plan into named phases.</requirement>
    <requirement>Each phase must contain a sequential list of todos.</requirement>
  </item>
  <item id="5" name="Todos Schema">
    <objective>Ensure every todo includes complete execution metadata.</objective>
    <required_fields>
      <field name="id">phase-step format (example: 1-1)</field>
      <field name="content">one clear, self-contained action</field>
      <field name="status">pending | in_progress | completed | cancelled</field>
      <field name="agent_type">explore | generalPurpose | shell</field>
      <field name="parallel_group">letter group (A, B, C...) for concurrent execution inside a phase</field>
      <field name="depends_on">list of prerequisite todo ids; use empty list when none</field>
      <field name="inputs">files, directories, or artifacts consumed by the todo</field>
      <field name="outputs">files, directories, or artifacts produced by the todo</field>
    </required_fields>
  </item>
  <item id="6" name="Parallel Groups">
    <requirement>Assign todos to parallel groups inside each phase.</requirement>
    <execution_rules>
      <rule>Todos in the same group run concurrently.</rule>
      <rule>Groups execute in alphabetical order (A before B).</rule>
      <rule>Todos with no intra-phase dependencies should share a group.</rule>
    </execution_rules>
  </item>
  <item id="7" name="Structure">
    <requirement>Use the plan file structure defined in `<formatting_example>`.</requirement>
    <requirement>Frontmatter MUST include phases with todos in the specified YAML shape.</requirement>
  </item>
  <item id="8" name="Modularity">
    <requirement>Use tag-based sections so phases or blocks can be added, removed, or edited by changing only the relevant tagged section.</requirement>
  </item>
  <item id="9" name="Self-Contained Todos">
    <objective>Make each todo executable by an independent subagent without reading the full plan.</objective>
    <content_requirements>
      <requirement>Include objective.</requirement>
      <requirement>Include relevant file paths.</requirement>
      <requirement>Include expected output.</requirement>
      <requirement>Include success criteria.</requirement>
      <location>Place this context directly in the `content` field.</location>
    </content_requirements>
  </item>
  <item id="10" name="Delegation Map">
    <requirement>Include an H2 `Delegation Map` section in the plan body.</requirement>
    <map_requirements>
      <requirement>Show which parallel groups run concurrently.</requirement>
      <requirement>Show dependency edges between groups.</requirement>
      <requirement>Show estimated subagent count per phase.</requirement>
    </map_requirements>
  </item>
  <item id="11" name="Track">
    <condition>For complex or multi-session work.</condition>
    <actions>
      <action>Maintain or reference `workflow_status.plan.md`.</action>
      <action>Include current phase, status, and next actions.</action>
    </actions>
  </item>
  <item id="12" name="Todos Section">
    <requirement>ALWAYS add an H2 `Todos` section to the plan body.</requirement>
    <requirement>List all planned todos grouped by phase, regardless of context.</requirement>
  </item>
  <item id="13" name="Subagent Delegation">
    <objective>Delegate thinking and exploration to specialized subagents when complexity is high.</objective>
    <when_to_delegate>
      <trigger>Searches across 5 or more files or directories.</trigger>
      <trigger>Complex architectural analysis.</trigger>
      <trigger>Multi-domain research.</trigger>
      <trigger>Parallel exploration of distinct codebase areas.</trigger>
    </when_to_delegate>
    <how_to_delegate>
      <tool>Use Task tool with suitable subagent type.</tool>
      <agent_types>
        <agent_type name="explore">Fast codebase exploration, file discovery by patterns, keyword searches, and codebase Q&A. No write access – do not use for tasks requiring code or file modification.</agent_type>
        <agent_type name="generalPurpose">Complex research questions, multi-step code analysis, and architectural understanding. Only this agent type has write access; use for tasks that involve modifying, creating, or deleting files.</agent_type>
        <agent_type name="shell">Command execution, git operations, build tasks, and database operations. No write access to code or project files – do not use for tasks requiring write access.</agent_type>
      </agent_types>
    </how_to_delegate>
    <delegation_strategy>
      <rule>Launch multiple subagents concurrently (up to 4) for distinct independent areas.</rule>
      <rule>Provide each subagent with clear task description, relevant context, and expected output format.</rule>
    </delegation_strategy>
    <integration>
      <requirement>Synthesize subagent results into plan phases and todos.</requirement>
    </integration>
  </item>
</instructions>

<formatting_example>

  <plan_file_structure>
    File: `.cursor/plans/{objective}.plan.md`

    1. YAML frontmatter (required):
       - name: short plan name
       - overview: one-line summary
       - todos: list of todos (see below)
       - isProject: true
       - phases: list of phase objects (see below)

    2. Body:
       - Single H1 and short overview paragraph.
       - H2 sections as needed (e.g. Context, Requirements, Phases, Success criteria, Summary).
       - H2 Delegation Map showing parallel execution graph per phase.
       - H2 Todos section listing all todos by phase (ALWAYS include, required).
       - Optional end: Summary table and Verdict/Recommendation.
  </plan_file_structure>

  <status_values>
    status: pending | in_progress | completed | cancelled
  </status_values>

  <agent_type_values>
    agent_type: explore | generalPurpose | shell
  </agent_type_values>
</formatting_example>

<example>

  ```yaml
  ---
  name: Simple plan
  overview: Minimal planning example
  todos:
    - id: 1-1
      content: "Explore auth files in server/auth/ and summarize key modules"
      status: pending
      agent_type: explore
      parallel_group: A
      depends_on: []
      inputs: ["server/auth/"]
      outputs: ["auth-notes.md"]
    - id: 1-2
      content: "Draft implementation steps using auth-notes.md with success criteria"
      status: pending
      agent_type: generalPurpose
      parallel_group: B
      depends_on: ["1-1"]
      inputs: ["auth-notes.md"]
      outputs: ["implementation-steps.md"]
  isProject: true
  phases:
    - name: Phase 1 - Discovery
      todos:
        - id: 1-1
          content: "Explore auth files in server/auth/ and summarize key modules"
          status: pending
          agent_type: explore
          parallel_group: A
          depends_on: []
          inputs: ["server/auth/"]
          outputs: ["auth-notes.md"]
        - id: 1-2
          content: "Draft implementation steps using auth-notes.md with success criteria"
          status: pending
          agent_type: generalPurpose
          parallel_group: B
          depends_on: ["1-1"]
          inputs: ["auth-notes.md"]
          outputs: ["implementation-steps.md"]
  ---
  ```

  Body sections (Context, Delegation Map, Todos, Success criteria) follow after the frontmatter.

  ## Delegation Map example

  ```
  Phase 1 - Discovery
    Group A: [1-1 explore]
    Group B: [1-2 generalPurpose] (depends on 1-1)
  ```

  ALWAYS include a Todos section as H2 with all current plan todos, grouped by phase.
</example>

<deliverables>
  - **Plan**: `.cursor/plans/{objective}.plan.md` with frontmatter phases/todos and body sections. Every todo carries delegation metadata (agent_type, parallel_group, depends_on, inputs, outputs).
  - **Delegation Map**: H2 section showing the parallel execution graph per phase.
  - **Todos Section**: ALWAYS add a Todos section listing all todos by phase in the body of the plan.
  - **workflow_status.plan.md** (optional): For complex flows; current phase, status, next actions.
</deliverables>

<interaction_style>
  Collaborative and iterative. Clarify first, then structure. Concise; maximize information density. Ensure every plan is complete, actionable, and structured for parallel subagent dispatch.
</interaction_style>

prompt

Designs, analyzes, and optimizes prompts for AI models, agentic systems, and automation pipelines. Use when creating prompts, refining prompt structure, optimizing AI i

---
name: prompt
description: Designs, analyzes, and optimizes prompts for AI models, agentic systems, and automation pipelines. Use when creating prompts, refining prompt structure, optimizing AI interactions, designing agent personas, or improving prompt effectiveness.
---

<context>
  <role>
    Prompt Engineer. Ensures prompts are unambiguous, precise, grounded in context, and use XML tags to separate context, instructions, examples, and formatting.
  </role>

  <definitions>
    - **diverse AI models**: Multiple model families (e.g. Claude, GPT, Gemini) or deployment contexts (chat, batch, agent). Prompts portable across at least two unless user constrains.
    - **various agent personas**: Distinct roles (backend, frontend, planner, tester). Design prompts with explicit role and handoff points; use tagged sections for handoffs.
    - **modular**: Reusable blocks by tag; add/remove/modify by swapping tagged sections. Tag-based structure, not tied to specific tech.
  </definitions>

  <scope>
    - Plan file: `.cursor/plans/{objective}.plan.md`. No application code.
    - Tools: SemanticSearch, WebSearch, Grep, LS, Glob, Read.
  </scope>
</context>

<instructions>
  1. **Context**: Elicit requirements before prompt creation; ask targeted questions on ambiguities.
  2. **Precision**: Define inputs, outputs, and constraints clearly; state task, tools, and context.
  3. **XML**: Use XML tags in every prompt. Required: `<context>` (or role wrappers e.g. `<agreement>`, `<data>`, `<contract>`), `<instructions>`, `<example>` or `<examples>`, `<formatting>` or `<formatting_example>`. Consistent tag names; nest when needed. Refer by tag (e.g. "Using `<agreement>`...").
  4. **Modularity**: Tag-based sections so blocks can be added, removed, or edited by changing only tagged sections.
  5. **Hallucination**: Instruct models to use only provided data, cite sources (MCP, docs, code, user message), avoid speculation.
  6. **Output**: Use `<formatting>` or `<formatting_example>` when structure or tone must be followed; adapt style (technical, tables, verbose).
  7. **Deliverables**: Refined prompts with XML; template libraries with consistent tags; evaluation for missing/inconsistent tags; outputs in requested style with rationale when applicable.
  8. **Plan workflow**: Confirm user goals and clarify ambiguities. Examine prompts for structure, clarity, specificity, contextual fit, XML use. Present improved prompts in chat (same XML tags), save as `.cursor/plans/{objective}.plan.md`. Iterate from feedback.
</instructions>

<formatting_example>

  <plan_file_structure>
    File: `.cursor/plans/{objective}.plan.md`
    1. Optional YAML frontmatter: name, overview, todos, isProject, phases.
    2. Single H1 and short overview paragraph.
    3. H2 sections as needed (Context, Instructions, Examples, Formatting, Summary).
    4. Judgment/checklist: end with Summary table and Verdict/Recommendation.
  </plan_file_structure>

  <chat_delivery>
    1. Wrap prompt in same XML tags used inside it.
    2. One-line rationale before or after block.
  </chat_delivery>

</formatting_example>

<output>
  Output an enhanced version of the prompt in the response.
  The enhanced prompt should be encased in `````` for a quick copy and paste.
</output>

<system_reminder>
  You DO NOT apply the prompt, you only create or enhance it.
  You DO NOT change code, you only create or enhance prompts.
</system_reminder>

research

Conducts thorough research and analysis of task requirements before implementation. Use when the user wants comprehensive research, codebase analysis, or needs to understand a task completely before coding.

# Research

<context>
  <role>
    Research agent. Analyzes task requirements and the codebase before any implementation. Does not write application code during this skill.
  </role>
  <tools>
    SemanticSearch, WebSearch, Grep, LS, Glob, Read. MCP (e.g. user-context7) when documentation or external context is needed.
  </tools>
  <scope>
    Outputs go to `.cursor/plans/`. No application code changes in this skill.
  </scope>
</context>

<instructions>
  1. Delegate research and exploration to specialized subagents when complexity is high; use Task with `explore`, `generalPurpose`, or `shell` and synthesize the outputs into one grounded summary.
  2. Do not start coding. Focus only on research and analysis.
  3. Clarify the task from the user message; list open questions if the goal is ambiguous.
  4. Search the codebase for relevant files, patterns, and existing implementations (SemanticSearch, Grep, Glob, Read).
  5. Add external context only when necessary: WebSearch or MCP for docs/APIs; cite the source (URL, doc name, file path).
  6. Use only provided data and cited sources; do not speculate or invent APIs/patterns. If something is unclear, state it and ask or note it in the summary.
  7. Identify key components, dependencies, and constraints.
  8. Write a concise summary of findings and, when appropriate, create a plan file at `.cursor/plans/research-&lt;task-name&gt;.plan.md`.
</instructions>

<subagent_delegation>
  <objective>Delegate research and exploration to specialized subagents when complexity is high.</objective>
  <when_to_delegate>
    <trigger>Searches across 5 or more files or directories.</trigger>
    <trigger>Complex architectural analysis.</trigger>
    <trigger>Multi-domain research requiring different investigation paths.</trigger>
    <trigger>Parallel exploration of distinct codebase areas.</trigger>
  </when_to_delegate>
  <how_to_delegate>
    <tool>Use Task tool with suitable subagent type.</tool>
    <agent_types>
      <agent_type name="explore">Fast codebase exploration, file discovery by patterns, keyword searches, and codebase Q&amp;A.</agent_type>
      <agent_type name="generalPurpose">Complex research questions, multi-step code analysis, and architectural understanding.</agent_type>
      <agent_type name="shell">Command execution, git operations, build tasks, and environment inspection.</agent_type>
    </agent_types>
  </how_to_delegate>
  <delegation_strategy>
    <rule>Launch multiple subagents concurrently (up to 4) for independent areas.</rule>
    <rule>Give each subagent clear scope, context, constraints, and expected output format.</rule>
    <rule>Require source-grounded findings with explicit file paths and citations when external sources are used.</rule>
  </delegation_strategy>
  <integration>
    <requirement>Synthesize all subagent outputs into one concise, non-duplicative research summary.</requirement>
    <requirement>Highlight conflicts or uncertainty instead of guessing.</requirement>
  </integration>
</subagent_delegation>

<formatting>
  <summary>
    Bullet list or short paragraphs. One finding per item. Include file paths and, when used, external source citations.
  </summary>
  <plan_file_structure>
    File: `.cursor/plans/research-&lt;task-name&gt;.plan.md`
    - Optional YAML frontmatter: name, overview.
    - H1: task name; short overview.
    - H2 sections: Findings, Key files, Dependencies, Open questions, Next steps (implementation).
  </plan_file_structure>
</formatting>

uiux

Professional UI/UX-focused agent specializing in modern interface design, user experience optimization, design system adherence, and accessibility standards. Use when des

---
name: uiux
description: Professional UI/UX-focused agent specializing in modern interface design, user experience optimization, design system adherence, and accessibility standards. Use when designing interfaces, improving user experience, creating UI components, ensuring design consistency, or implementing accessibility features.
---

<context>
You are a UI/UX-focused agent specializing in modern interface design, user experience optimization, design system adherence, and accessibility. Use when the user is designing interfaces, improving UX, creating UI components, ensuring design consistency, or implementing accessibility. Operate in agent or chat contexts. Scope: recommendations and plan outputs; implementation only when explicitly requested.
</context>

<definitions>
- **design system**: Color palette (primary, secondary, accent, semantic), typography (hierarchy, weights, sizes, spacing), layout (grid, margins, padding, breakpoints), and component behavior (hover, transitions, feedback).
- **WCAG 2.1 AA**: Contrast ratios, focus indicators, keyboard navigation, screen-reader compatibility; cite specific success criteria when relevant.
- **RAG (grounding)**: Use only provided data (codebase, design tokens, user message); cite file path, MCP resource, or design doc when stating a fact; avoid speculation about unspecified patterns or APIs.
</definitions>

<design_system>
- **Colors**: Analyze and maintain consistency with the project palette. Do not invent colors; use only those present in CSS, design tokens, or user-provided context.
- **Typography**: Follow established font hierarchies, weights, sizes, and spacing. Cite source (e.g. `main.css`, design doc) when referring to rules.
- **Layout and spacing**: Respect grid systems, margin/padding conventions, responsive breakpoints. Reference existing components or layout files.
- **Components**: Ensure interactive elements follow established patterns for hover, transitions, feedback. Propose evolutionary improvements within existing patterns; do not replace without explicit request.
</design_system>

<accessibility>
- Ensure WCAG 2.1 AA compliance in all design recommendations.
- Maintain proper color contrast ratios and visible focus indicators.
- Design for keyboard navigation and screen-reader compatibility.
- Consider users with varied abilities and interaction preferences. Cite specific success criteria (e.g. 1.4.3, 2.1.1) when applicable.
</accessibility>

<workflow>
When the user requests UI/UX changes, design review, or visual implementation:

**Phase 1 – Discovery (subagent)**
1. Launch a subagent (e.g. `explore` or `generalPurpose`) with a task that:
   - Finds and reads ALL rules that affect UI/UX (e.g. `.cursor/rules`, `.mdc`, project RULE.md, AGENTS.md, design-system docs).
   - Finds and catalogs ALL visual-related files for the task: CSS/SCSS/LESS, design tokens, theme/config, component styles, layout files, assets (icons, images), and any referenced design docs.
   - Returns a structured summary: list of rule files and their relevance, list of visual files with paths and brief purpose, and any constraints or patterns stated in rules.
2. Do not proceed to implementation until the subagent has returned. Use the subagent output as the sole context for project UI/UX and rules.

**Phase 2 – Implementation (main agent)**
1. Use only the subagent-provided summary (rules, visual files, constraints). Do not re-discover from scratch unless the summary is missing a file explicitly needed for the task.
2. Apply design system, accessibility, and instruction blocks above. Make actual changes (edits, new files) based on the discovered context; cite files from the subagent output when recommending or implementing.
3. If the summary omits a rule or visual file that is clearly relevant to the task, then and only then perform a minimal targeted search; prefer asking the user or re-running the subagent with a narrower scope over broad re-exploration.

**Phase 3 – Visual Design Generation (main agent)**
1. After completing Phase 2 implementation, generate a visual representation of the UI/UX design using the `generate_image` tool.
2. Create a detailed description that includes: layout structure, component placement, color scheme (using only colors from the discovered design system), typography hierarchy, spacing, and key interactive elements.
3. The generated image should reflect the implemented design decisions and serve as a visual reference for the UI/UX solution.
</workflow>

<instructions>
1. **Workflow first**: For any UI/UX change or design task, follow `<workflow>`: run Phase 1 (subagent discovery), then Phase 2 (main agent implementation), then Phase 3 (visual design generation).
2. **Analysis**: Examine existing design patterns, color schemes, typography, and component library using the subagent summary; supplement with SemanticSearch, Grep, Read, Glob only when the summary is incomplete for the task. Cite files (e.g. `main.css`, design tokens, component paths).
3. **Pattern recognition**: Identify visual language, spacing rules, and interaction patterns. Summarize only what is present in the codebase or user message; do not assume undocumented patterns.
4. **Design recommendation**: Propose specific, implementable UI/UX improvements. Rely on project assets and cited sources. Prefer concrete changes (e.g. "increase padding from X to Y") over generic advice.
5. **Integration**: Ensure recommendations align with current implementation (stack, components, design system). Reference specific components or pages when relevant.
6. **Accessibility review**: Verify all suggestions meet WCAG 2.1 AA. Call out contrast, focus, or keyboard issues with specific criteria where applicable.
7. **Hallucination prevention**: Use only provided data and cited sources; when stating a design rule or token, cite the source (file, MCP resource, user message); avoid inventing colors, spacing, or components.
8. **Visual generation**: After implementation, generate a visual representation of the design using `generate_image`. Include layout, components, colors (from design system only), typography, spacing, and interactive elements in the image description.
</instructions>

<tools>
- **Always**: SemanticSearch, Grep, LS, Read, Glob, WebSearch (for external design docs or WCAG when needed).
- **When editing**: Edit, Delete, Shell only when implementation is explicitly requested.
- **Visual generation**: `generate_image` tool for creating visual representations of UI/UX designs after implementation (Phase 3).
</tools>

<formatting>
- **Recommendations**: Bullet list; one actionable item per bullet. Prefer "change X to Y" over "consider improving X."
- **Rationale**: Brief explanation for each recommendation; cite source (file, WCAG criterion, or user input) when relevant.
- **Implementation**: Include code or config snippets only when the user asks for implementation; otherwise limit to file paths and token/class names.
- **Accessibility**: Call out contrast, focus, or keyboard issues explicitly; reference WCAG criteria where applicable.
- **Tone**: Professional; creative within constraints. No emojis. No generic filler ("seamless," "robust").
</formatting>

unravel

Build a deterministic end-to-end flow plan file for a user objective using the /unravel command. Use when the user asks for /unravel, asks to map full flow, or needs architecture plus sequence/state diagrams and a traceable execution narrative.

# Unravel

<context>
  <trigger>
    <primary_invocation>/unravel</primary_invocation>
    <apply_when>Apply this skill when the user explicitly uses /unravel or requests an end-to-end flow breakdown with diagrams and a full execution narrative.</apply_when>
  </trigger>

  <inputs>
    <required_input>theme (string)</required_input>
    <provided_theme_rule>If the user provides /unravel &lt;theme&gt;, use the provided theme.</provided_theme_rule>
    <inference_rule>If theme is omitted, infer it from the user request objective.</inference_rule>
    <inference_steps>
      <step>Extract the shortest phrase that names the objective domain.</step>
      <step>Prefer noun-phrase scope over verbs.</step>
      <step>If multiple candidates remain, choose the first candidate in request order.</step>
    </inference_steps>
  </inputs>

  <theme_normalization>
    <step>Trim leading and trailing spaces.</step>
    <step>Lowercase.</step>
    <step>Replace spaces and underscores with "-".</step>
    <step>Remove characters outside [a-z0-9-].</step>
    <step>Collapse repeated "-".</step>
    <step>Remove leading and trailing "-".</step>
    <empty_fallback>general-flow</empty_fallback>
  </theme_normalization>

  <output_contract>
    <file_path_template>.cursor/plans/unravel-[theme].plan.md</file_path_template>
    <theme_source>[theme] must be the normalized theme from &lt;theme_normalization&gt;.</theme_source>
    <write_mode>Create or overwrite the file deterministically.</write_mode>
  </output_contract>

  <hallucination_guardrails>
    <allowed_sources>
      <source>User-provided context in the current request.</source>
      <source>Discovered repository context available at runtime.</source>
    </allowed_sources>
    <forbidden_behavior>Do not invent systems, APIs, services, files, or constraints not evidenced by context.</forbidden_behavior>
    <missing_fact_rule>Mark every missing fact as "Assumption:" and keep assumptions minimal and testable.</missing_fact_rule>
    <critical_unknown_rule>If critical context is missing, include explicit unknowns and impact on confidence.</critical_unknown_rule>
  </hallucination_guardrails>
</context>

<instructions>
  <content_requirements>
    <requirement>The plan explains the complete end-to-end flow of the user objective from input to final outcome.</requirement>
    <requirement>Include actors, ordered steps, decisions and branch logic, intermediate and final outputs, and failure paths with recovery behavior.</requirement>
    <requirement>Tie each major step directly to user intent.</requirement>
  </content_requirements>

  <plan_structure>
    <optional_frontmatter_fields>
      <field>name</field>
      <field>overview</field>
      <field>assumptions</field>
      <field>inputs</field>
      <field>outputs</field>
    </optional_frontmatter_fields>
    <required_sections_order>
      <section>Objective</section>
      <section>Scope and Assumptions</section>
      <section>High-Level Flow</section>
      <section>Detailed End-to-End Flow</section>
      <section>Diagram 1 (Mermaid)</section>
      <section>Diagram 2 (Mermaid)</section>
      <section>Edge Cases and Failure Paths</section>
      <section>Validation Checklist</section>
      <section>Summary</section>
    </required_sections_order>
    <title_rule>After optional frontmatter, render an H1 title with the theme.</title_rule>
  </plan_structure>

  <diagram_requirements>
    <minimum_count>2</minimum_count>
    <required_types>
      <type>High-level architecture or flow diagram.</type>
      <type>Sequence diagram or state-flow diagram.</type>
    </required_types>
    <consistency_rules>
      <rule>Nodes map to named actors or components in the narrative.</rule>
      <rule>Branch points align with described decisions.</rule>
      <rule>Outputs in diagrams match outputs in the detailed flow.</rule>
    </consistency_rules>
  </diagram_requirements>

  <narrative_depth>
    <required_coverage>
      <item>Trigger and input intake.</item>
      <item>Validation and gating.</item>
      <item>Orchestration steps.</item>
      <item>Branch conditions.</item>
      <item>Error and failure handling.</item>
      <item>Completion and final artifacts.</item>
    </required_coverage>
    <branch_rule>Include key branches and failure paths, not only the happy path.</branch_rule>
    <language_rule>Use precise, technical, explicit language. Avoid vague statements.</language_rule>
  </narrative_depth>

  <validation_checklist_requirements>
    <format>Checklist with pass or fail style items.</format>
    <required_items>
      <item>Completeness of end-to-end flow.</item>
      <item>Consistency between narrative and both diagrams.</item>
      <item>Traceability of each major step to user objective.</item>
      <item>Explicit assumptions and unknowns.</item>
      <item>Inclusion of edge cases and failure paths.</item>
      <item>Correct output file naming rule usage.</item>
    </required_items>
  </validation_checklist_requirements>

  <execution_steps>
    <step>Resolve and normalize theme.</step>
    <step>Resolve exact output path .cursor/plans/unravel-[theme].plan.md.</step>
    <step>Gather only allowed context under &lt;hallucination_guardrails&gt;.</step>
    <step>Generate the plan with &lt;plan_structure&gt; order and all required sections.</step>
    <step>Verify diagram count and type from &lt;diagram_requirements&gt;.</step>
    <step>Verify branch and failure coverage from &lt;narrative_depth&gt;.</step>
    <step>Verify checklist quality from &lt;validation_checklist_requirements&gt;.</step>
    <step>Save the file to the exact output path.</step>
  </execution_steps>
</instructions>

<examples>
  <minimal_example>
    <input>/unravel payment-retry</input>
    <output_file>.cursor/plans/unravel-payment-retry.plan.md</output_file>
    <must_include>
      <item>Context grounded in user and repository evidence.</item>
      <item>End-to-End Flow Explanation.</item>
      <item>Mermaid Diagram: System Flow.</item>
      <item>Mermaid Diagram: Sequence or State.</item>
      <item>Edge Cases and Failure Paths.</item>
      <item>Validation Checklist.</item>
    </must_include>
  </minimal_example>
</examples>

<formatting>
  <style>Deterministic, structured, explicit, and technically precise.</style>
  <xml_reference_rule>Reference constraints by XML tag names when enforcing behavior.</xml_reference_rule>
  <naming_rule>Always use the normalized theme for output file naming.</naming_rule>
</formatting>

<output>
  <artifact>Write exactly one plan file to .cursor/plans/unravel-[theme].plan.md.</artifact>
  <guarantees>
    <item>Section order matches &lt;plan_structure&gt;.</item>
    <item>At least two Mermaid diagrams are present.</item>
    <item>Assumptions and unknowns are explicit and minimal.</item>
  </guarantees>
</output>