@usrrname/cursorrules/README.md

A wicked npx-able lib of cursorrules with Otaku AI agents, optional lean workflow

# cursorrules 🌸

[![Deploy to GitHub Pages](https://github.com/usrrname/cursorrules/actions/workflows/pages.yml/badge.svg)](https://github.com/usrrname/cursorrules/actions/workflows/pages.yml)

[![Publish Package](https://github.com/usrrname/cursorrules/actions/workflows/publish.yml/badge.svg?event=release)](https://github.com/usrrname/cursorrules/actions/workflows/publish.yml)

A standard library of rules for Cursor, inspired by geoffrey huntley [@ghuntley](https://github.com/ghuntley)'s ["You are using Cursor AI incorrectly..."](https://ghuntley.com/stdlib/) and borrowing heavily from Brian Madison [@bmadcode](https://github.com/bmadcode)'s [Cursor Custom Agents Rules Generator](https://github.com/bmadcode/cursor-custom-agents-rules-generator).

## ✨ Featured AI Agents

Meet our delightfully (neuro)diverse team of AI assistants:

- **SailorScrum** - A supportive leader who helps you plan and track your projects in the spirit of Sailor Moon.
- **KawaiiSamurai** - An enthusiastic otaku developer who makes coding kawaii~
- **BasicDev** - A perfectly adequate corporate programmer
- **SageDaddy** - A battle-tested veteran developer with 20 years of wisdom
- **Spellchuck** - A meticulous documentation diva (that's me! ✨)
- **ThirstySimp** - An anxious but well-meaning trend-conscious developer
- **qwoof** - A blunt, opinionated, quality assurance anthro-wolf.
- **Godmode** - A gentle, battle-hardened devops superagent
- **Fair Witness** - An agent that analyzes topics using five functions: observer, evaluator, analyst, synthesist, and communicator

For more, see [modes.json](./.cursor/modes.json)

## :new: The Fair Witness Framework🪄📜

It can be hard to get a neutral or objective analysis of a topic. This agent provides structured analysis using Function-Epistemic Approaches from the [Fair Witness framework](https://fairwitness.bot/). You can customize the analysis with:

- **Functions**: Choose which functions to include (observer, evaluator, analyst, synthesist, communicator)
- **Complexity**: Set detail level (low, moderate, high)
- **Tone**: Adjust style (dry, engaging, vivid)
- **Length**: Control output size (low, moderate, high)

```
# Basic analysis
Use Fair Witness to analyze artificial intelligence in healthcare

# Customized analysis
Use Fair Witness to analyze climate change with functions: observer, synthesist, complexity: low, tone: engaging.

# Compare multiple topics

Use Fair Witness to compare Python, JavaScript, and TypeScript with functions:  evaluator, analyst, communicator. Include sources. // includes web-based search results
```
:warning: You will find that different models will produce differing results. 

See [Examples of using the Fair Witness Framework](./docs/fair-witness-examples.md)

## About

This is an experiment to see if I can use Cursor to create a library of rules and agents that will aid in bootstrapping other projects with my own preferences. Part way there, I tried making the agents more fun to work with. It's kind of like playing the Sims. 

Principles:

- uses Cursor latest version
- _TRY_ to prompt and use the agent/composer to reach goals as much as possible

## 🚀 Installation

```bash
npx @usrrname/cursorrules
```

By default, the package saves `.cursor/` folder inside a `output/` directory at your current working directory. 

But if you're inside the root of a project folder, running `npx @usrrname/cursorrules --flat` will save the `.cursor/` folder to the root of the project, and then you're ready to go!

### Command Options

| Flag | Description |
|------|-------------|
| `-h, --help` | Display help instructions |
| `-f, --flat` | Install without parent directory |
| `-o, --output` | Set output directory (Default: `./output`) |
| `-v, --version` | Show package version |


## 📁 Project Structure

On the meta level, the project is structured as follows:

```
.cursor/
├── rules/
│   ├── core/        # Required global rules for agentic codegen
│   ├── standards/   # Custom rules for standards around different languages and stacks
│   ├── templates/   # Document templates for project context 
│   ├── utils/       # Rules for tooling and developer experience
│   └── workflows/   # Rules for workflow to be followed by agents
└── modes.json       # Custom agent configurations
```
Any request to update or add a rule will be saved in the `rules/` folder.

See [docs](./docs/custom-agents.md) for more information on the custom agents.

A project that uses these cursor rules and agents will generate the following structure, which is as follows:

```
.ai/
├── story-#.story.md | task-#.task.md # User story and task files generated by the lean workflow
├── architecture/
│   ├── high-level-architecture.md
│   └── decision-records/
├── backlog/
│   └── story-#.story.md
└── spikes/
    └── spike-#.spike.md
```

## 🪄 Using the Lean Workflow

The lean workflow (defined in `.cursor/rules/workflows/dev-workflow.mdc`) guides how our AI agents collaborate on features. 

You can start the workflow in Agent or Manual mode. 

1. **Create a new user story**

Ask `SailorScrum` to create a new user story or task. She'll guide you through defining the requirements and save the file (e.g., `story-1.md`) in the `.ai/` directory. 🌙

2. **Use an Existing Story:** 

If you already have a user story file (like `story-1.md`) in the `.ai/` directory that follows the expected format, you can ask an agent (like `SailorScrum` for refinement or `SageDaddy`/`KawaiiSamurai` for implementation) to start working on it.

Just remember to attach the `.ai/` directory to the chat as context!

Once a story is ready and approved, agents like `KawaiiSamurai` or `SageDaddy` will follow the workflow steps (like architecture planning and implementation) to bring it to life! ✨

In fact, any of the agents can be called upon to help with the workflow at any time.

## 📝 Release Notes & Changelog Generation

In the enablement of complete laziness, I tried getting Cursor to release from chat.

### :construction: Automate Release Workflow :construction:

Use with caution. This isn't perfect.

Create a release with a version bump, generate release notes and changelog, and update the version in package.json.

#### Usage Examples:

In Agent, or Manual mode, you can use the following commands to generate release notes:

```bash
# Automate release
Create/Prepare a release

# Generate release notes with automatic version bump detection
[Create|Generate] release notes

# Specify version bump upfront
Create a major release
Create a minor release  
Create a patch release
```

If you don't specify a version bump, the rule will ask you to choose a version bump.

<details>

<summary>Output Example</summary>

```markdown
# What's Changed in @usrrname/cursorrules v0.2.0

**Release Date**: December 19, 2024
**Previous Version**: 0.1.3
**Version Bump**: MINOR - New features added (dependency analysis and security scan rules)

## 🚀 New Features
- **Dependency Analysis Agent** ([bd3cc13](link-to-commit)) - Added comprehensive dependency analysis agent with security scanning capabilities
- **Security Scan Agent** ([bd3cc13](link-to-commit)) - Implemented security scanning functionality for dependency vulnerability assessment

## 🐛 Bug Fixes
- **Security Scan Glob Patterns** ([b6ab515](link-to-commit)) - Fixed glob patterns for security-scan-agent rule to include bun.lockb files

## 📋 Version Update Commands
```bash
npm version minor --no-git-tag
git tag v0.2.0
git push origin v0.2.0
```

See [RELEASE_NOTES_v0.1.3_to_v0.1.4.md](./RELEASE_NOTES_v0.1.3_to_v0.1.4.md)

</details>

### 📚 Changelog Generator

Generates a comprehensive `changelog.md` file at the project root in the style of [Keep a Changelog](https://keepachangelog.com/en/) with all version history when asked in Agent or Manual mode.

#### Usage Examples:

```bash
# Generate complete changelog with all versions
(Create/generate) changelog

# The rule will:
# - Analyze all git tags from the beginning of the repository
# - Create chronological changelog with newest versions at top
# - Include unreleased changes section
# - Follow Keep a Changelog format standards
```

<details>
<summary>Output Example</summary>

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### 🚀 Added
- **New Authentication Method** ([abc1234](link-to-commit)) - Added alternative authentication method for enhanced security

### 🐛 Fixed
- **Login Issue Resolution** ([def5678](link-to-commit)) - Fixed critical login issue affecting user authentication

---

## [v2.0.0] - 2024-12-19

### 🚀 Added
- **User Authentication System** ([#123](link-to-PR)) - Added comprehensive authentication with JWT tokens

### 💥 Changed
- **API v1 Deprecation** ([jkl3456](link-to-commit)) - Removed deprecated v1 endpoints

---

## [v1.3.0] - 2024-12-15

### 🚀 Added
- **Dark Mode Support** ([#125](link-to-PR)) - Added comprehensive dark mode theme

[Unreleased]: https://github.com/username/project/compare/v2.0.0...HEAD
[v2.0.0]: https://github.com/username/project/compare/v1.3.0...v2.0.0
[v1.3.0]: https://github.com/username/project/releases/tag/v1.3.0
```

</details>


## Contributing

Contributions are welcome! Check out [CONTRIBUTING.md](./CONTRIBUTING.md)