Brief

AI-optimized configuration generator for Cursor IDE, Claude Code, and Qoder.

Brief auto-detects your tech stack and generates production-ready AI configuration files with best practices baked in.

Installation

# Use directly with npx
npx @tszhim_tech/brief init

# Or install globally
npm install -g @tszhim_tech/brief

Quick Start

Framework-Specific Magic 🪄

brief magic nextjs     # Generate AI configs for a Next.js project (App Router + TS + Tailwind)
# more framework kits coming soon

Advanced Mode ⚙️

brief init --advanced      # Full customization
brief init --templates springboot,security,database
brief detect               # Show detected project info
brief templates            # List available templates

Features

• Framework-Specific Magic — One-command AI config generation for existing projects
• Auto-Detection — Frameworks, languages, databases, ORMs, testing tools
• Multi-Tool Support — Cursor, Claude Code, Qoder configurations
• Smart Templates — Context-aware rules based on your stack
• Merge Mode — Intelligently merge with existing configs
• Production Ready — Security, testing, and performance patterns included

Supported Tech

Category	Technologies
Languages	TypeScript, JavaScript, Python, Java, Go
Frontend	React, Next.js, Vue, Nuxt, Svelte, Astro
Backend	Express, Fastify, NestJS, FastAPI, Django, Spring Boot
Databases	PostgreSQL, MySQL, MongoDB, SQLite, Redis
ORMs	Prisma, Drizzle, TypeORM, Sequelize, SQLAlchemy
Testing	Jest, Vitest, Bun Test, Pytest, Playwright, Cypress
Build	Vite, Webpack, Turbopack, Bun, esbuild

Commands

Command	Description
brief init	Initialize AI configuration (interactive wizard)
brief magic <kit>	Generate framework-specific AI configs (e.g. Next.js)
brief detect	Detect and display project information
brief add <template>	Add a specific template
brief remove <template>	Remove a template
brief sync	Re-detect and sync configuration
brief validate	Validate configuration files
brief templates	List all available templates

Common Options

brief init --tool cursor      # Generate only Cursor rules
brief init --tool claude      # Generate only Claude config
brief init --tool qoder       # Generate only Qoder config
brief init --merge            # Smart merge with existing files
brief init --templates react,testing,security

Generated Files

Cursor IDE — .cursor/rules/*.mdc

.cursor/rules/
├── core.mdc              # Core coding standards
├── memory-management.mdc # AI context optimization
├── typescript.mdc        # Language-specific rules
├── react.mdc             # Framework patterns
├── testing.mdc           # Testing best practices
├── security.mdc          # Security guidelines
└── ...

Claude Code — CLAUDE.md + .claude/

CLAUDE.md                 # Main configuration
.claude/
├── settings.json         # Claude settings
└── skills/
    ├── testing.md
    └── git-workflow.md

Qoder — .qoder/rules/*.md

.qoder/rules/
├── core.md               # Core standards
├── quick-reference.md    # How to use @ references
├── requirements-spec.md  # Quest mode requirements
├── project-info.md       # Tech stack info
├── best-practices.md     # Coding best practices
├── typescript.md         # Language rules (from common)
├── react.md              # Framework patterns (from common)
├── nextjs.md             # Next.js conventions (from common)
├── security.md           # OWASP Top 10
├── testing.md            # Testing patterns
├── api-design.md         # API conventions
└── ...                   # + other detected tech

Architecture

Unified Template System

Brief uses a single-source, multi-target architecture for templates. Common templates (TypeScript, React, security, etc.) are authored once and automatically transformed for each AI tool:

common/typescript.mdc.hbs (single source)
    │
    ├─► Cursor:  .cursor/rules/typescript.mdc
    │            frontmatter: { description, globs, priority, tags }
    │
    ├─► Claude:  (included via CLAUDE.md aggregation)
    │
    └─► Qoder:   .qoder/rules/typescript.md
                 frontmatter: { description }  ← Cursor fields removed

Key benefits:

• DRY — One template, multiple outputs
• Consistency — Same best practices across all AI tools
• Maintainability — Update once, apply everywhere

Runtime Transformation

When generating for non-Cursor targets, Brief automatically:

1. Path transformation — .cursor/rules/*.mdc → .qoder/rules/*.md
2. Frontmatter transformation — Removes Cursor-specific fields (globs, priority, alwaysApply, tags)

This is handled by path-resolver.ts.

Generator Factory

All generators (Cursor, Claude, Qoder, JetBrains, Shared) use a common factory pattern:

export const cursorGenerator = createGenerator({
  name: "Cursor Rules Generator",
  target: "cursor",
  getTemplates: getCursorTemplates,
});

This eliminates ~250 lines of duplicate code across generators.

Roadmap

Completed ✅

• Interactive wizard with project detection
• Cursor, Claude Code, Qoder generators
• TypeScript, JavaScript, Python, Java templates
• React, Next.js, Vue, Express, FastAPI, Spring Boot support
• Prisma ORM patterns
• AI memory management templates
• Smart merge with conflict resolution
• Dry-run and backup modes
• Next.js magic kit (AI config generation for Next.js projects)
• Unified template system (single-source, multi-target)
• Generator factory pattern (DRY code architecture)

Phase 1: Quick Start & Profiles (Next 2-3 releases)

• Quick Start Commands - One-command project scaffolding

  brief init spring-api     # Spring Boot backend
  brief init react-app      # React frontend
  brief init fullstack      # Full-stack opinionated setup

• Profile System - Save and reuse configurations

  brief profile save my-stack    # Save current setup
  brief init --profile my-stack  # Reuse anytime

• Enhanced Detection - Smarter project type guessing
• Template Recommendations - Context-aware suggestions

Phase 2: Community & Collaboration (3-6 months)

• Template Marketplace - Browse and share community templates
• Team Profiles - Organization-wide standard configurations
• IDE Integration - Auto-configure VS Code, IntelliJ
• Cloud Sync - Sync profiles across all your machines

Phase 3: Intelligence & Scale (6+ months)

• AI-Powered Suggestions - Learn from usage patterns
• Template Builder UI - Visual template creation tool
• Enterprise Features - Compliance scanning, security audits
• Plugin System - Third-party template providers

Planned

• Standalone binary distribution
• VS Code extension
• Template marketplace
• Team/organization templates
• Cloud sync across machines
• AI-powered template generation

Contributing

Development Setup

# Clone the repository
git clone https://github.com/kelvin6365/brief.git
cd brief

# Install dependencies
bun install

# Build the project
bun run build

Link Locally

To test the CLI locally before publishing:

# Option 1: Using bun
bun link                    # Register the package globally
bun link @tszhim_tech/brief # Link in another project

# Option 2: Using npm
npm link                    # Register the package globally
cd /path/to/test-project
npm link @tszhim_tech/brief # Use in another project

# Option 3: Run directly without linking
bun run cli init            # Run from the project directory

Development Workflow

bun run dev          # Watch mode for development
bun run type-check   # TypeScript type checking
bun test             # Run tests
bun test --watch     # Run tests in watch mode
bun run build        # Build for production

Submitting Changes

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (bun test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Unlink

# When done testing
bun unlink @tszhim_tech/brief  # In the test project
bun unlink                      # In the brief directory

# Or with npm
npm unlink @tszhim_tech/brief
npm unlink

Documentation

• Architecture Guide
• Tech Stack Details

License

MIT — see LICENSE for details.

---

Issues · Documentation · NPM Package