Resit Engineering Rules CLI

A corporate CLI tool to bootstrap projects and install engineering rules for AI-assisted development tools like Windsurf, Cursor, Continue, and Claude Code.

Features

• 🚀 Easy Initialization: Quickly set up engineering rules in any project
• 🔍 Auto-Detection: Automatically detects project type (Odoo, React, WordPress, Python, Ruby on Rails)
• 📦 Modular Rules: Combines base engineering rules with stack-specific guidelines
• 🔄 Update Support: Keep your rules up-to-date with the latest version
• 🏥 Health Checks: Verify your rules are properly configured
• 🎯 Extensible: Plugin-style architecture for adding new stacks and rules

Installation

Global Installation (Recommended)

npm install -g @resit/engineering-rules

Local Installation

npm install --save-dev @resit/engineering-rules

Usage

Initialize Rules

Initialize engineering rules in your current project:

resit init

This command will:

1. Detect your project type (if possible)
2. Prompt you to select a stack if detection fails
3. If the stack has optional modules, prompt to select them (checkbox list)
4. Generate a .windsurf directory with:
   • architecture.md - Project architecture documentation
   • prompts.md - Helpful prompts for AI assistants
   • rules/ - Folder containing:
     • rules.md - Combined engineering and stack-specific rules
     • Selected optional module folders/files (preserves folder structure)

Check Rules Health

Verify that your engineering rules are properly configured:

resit doctor

This command checks for:

• Existence of .windsurf directory
• Presence of required files
• Unprocessed template variables
• Outdated rules

Update Rules

Update your rules to the latest version:

resit update

This command will:

1. Detect your current stack from existing rules
2. Update all rule files to the latest version
3. Preserve your stack selection

Show Version

Display the CLI version:

resit version

Supported Stacks

• Odoo - Odoo ERP development
• React - React web applications
• WordPress - WordPress plugins and themes
• Python - Python applications
• Ruby on Rails - Ruby on Rails applications

Project Structure

resit-engineering-rules/
├── src/
│   ├── cli.ts                 # Main CLI entry point
│   ├── commands/              # CLI commands
│   │   ├── init.ts
│   │   ├── doctor.ts
│   │   ├── update.ts
│   │   └── version.ts
│   ├── core/                  # Core modules
│   │   ├── ruleLoader.ts      # Loads and combines rules
│   │   ├── stackResolver.ts   # Detects and manages stacks
│   │   ├── templateEngine.ts  # Renders templates
│   │   └── types.ts           # TypeScript types
│   └── utils/                 # Utility modules
│       ├── logger.ts
│       └── fs.ts
├── rules/                     # Rule definitions
│   ├── base/                  # Base rules for all projects
│   │   ├── engineering.md
│   │   └── git.md
│   ├── stacks/                # Stack-specific rules
│   │   ├── odoo.md
│   │   ├── react.md
│   │   ├── wordpress.md
│   │   ├── python.md
│   │   └── ruby.md
│   └── modules/               # Optional modules (add your custom modules here)
│       ├── odoo-localization-chile/  # Directory module (multiple .md files)
│       │   ├── odoo-l10n-cl-overview.md
│       │   ├── odoo-l10n-cl-dte.md
│       │   └── odoo-l10n-cl-xml-templates.md
│       ├── odoo-pos.md        # Single file module
│       └── .gitkeep
├── templates/                 # Template files
│   └── windsurf/
│       ├── rules.md
│       ├── architecture.md
│       └── prompts.md
└── package.json

Architecture

Plugin-Style Design

The CLI uses a modular, plugin-style architecture that makes it easy to add new stacks and rules without modifying core code.

Adding a New Stack

1. Create a new rule file in rules/stacks/:

# Example: rules/stacks/nextjs.md

2. Add the stack to StackResolver:

// src/core/stackResolver.ts
{
  id: 'nextjs',
  name: 'Next.js',
  description: 'Next.js applications',
  ruleFiles: ['nextjs.md'],
}

3. Add detection logic (optional):

// src/core/stackResolver.ts
if (fs.existsSync(path.join(projectPath, 'next.config.js'))) {
  return 'nextjs';
}

Adding New Base Rules

Create a new markdown file in rules/base/ and update RuleLoader.loadBaseRules() to include it.

Adding Optional Modules to a Stack

Optional modules allow you to add technology-specific rules that users can select during initialization. For example, Odoo projects can select modules for Chilean localization, POS, accounting, or government projects.

Module formats supported:

Modules can be either:

• Single file: rules/modules/odoo-pos.md
• Directory with multiple files: rules/modules/odoo-localization-chile/ (containing multiple .md files)

1. Create the module rules:

Option A - Single file module:

# Simple module with all rules in one file
rules/modules/odoo-pos.md

Option B - Directory module (recommended for complex modules):

# Complex module with multiple organized files
rules/modules/odoo-localization-chile/
├── odoo-l10n-cl-overview.md
├── odoo-l10n-cl-dte.md
├── odoo-l10n-cl-xml-templates.md
└── odoo-l10n-cl-sii-integration.md

When using a directory, all .md files inside will be loaded and combined (sorted alphabetically).

2. Add the module to the stack definition:

// src/core/stackResolver.ts
{
  id: 'odoo',
  name: 'Odoo',
  description: 'Odoo ERP development',
  ruleFiles: ['odoo.md'],
  optionalModules: [
    {
      id: 'odoo-localization-chile',
      name: 'Localización Chile',
      description: 'Reglas para localización chilena (facturación electrónica, DTE, etc.)',
      ruleFile: 'odoo-localization-chile.md',
    },
    {
      id: 'odoo-pos',
      name: 'Point of Sale (POS)',
      description: 'Reglas para desarrollo de módulos POS',
      ruleFile: 'odoo-pos.md',
    },
    // Add more modules as needed
  ],
}

3. How it works:

• During resit init, if a stack has optional modules, the CLI will prompt the user with a checkbox list
• Users can select one, multiple, or no optional modules
• Selected modules are loaded and appended to the generated rules
• The selection is tracked in the architecture.md file

Example stacks with optional modules:

• Odoo: Chilean localization, POS, Accounting, Government
• Node.js/React: Socket.IO, PostgreSQL, MongoDB
• Python: Django, FastAPI, Flask, SQLAlchemy

Benefits:

• Keep base stack rules clean and focused
• Allow project-specific customization
• Easy to extend without modifying core files
• Users only get the rules they need

Core Modules

• StackResolver: Manages available stacks and auto-detects project types
• RuleLoader: Loads and combines base and stack-specific rules
• TemplateEngine: Renders templates with variables and generates output files

Development

Setup

# Clone the repository
git clone <repository-url>
cd resit-engineering-rules

# Install dependencies
npm install

# Build the project
npm run build

# Link for local testing
npm link

Build

npm run build

Watch Mode

npm run dev

Testing Locally

After building and linking:

cd /path/to/test/project
resit init

Publishing to npm

Prerequisites

1. Create an npm account at https://www.npmjs.com
2. Login to npm:

npm login

Publishing Steps

1. Update Version

Update the version in package.json:

npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

2. Build the Project

npm run build

3. Test the Package

# Test locally
npm link
cd /path/to/test/project
resit init

# Or test with npm pack
npm pack
npm install -g resit-engineering-rules-1.0.0.tgz

4. Publish

# For scoped packages (recommended)
npm publish --access public

# For unscoped packages
npm publish

5. Verify Publication

npm info @resit/engineering-rules

Publishing Checklist

• [ ] All tests pass
• [ ] Version number updated
• [ ] CHANGELOG updated (if applicable)
• [ ] README is up-to-date
• [ ] Build succeeds without errors
• [ ] Package tested locally
• [ ] Git changes committed and pushed
• [ ] Published to npm
• [ ] Verified installation: npm install -g @resit/engineering-rules

Continuous Deployment (Optional)

Using GitHub Actions

Create .github/workflows/publish.yml:

name: Publish to npm

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm run build
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Add your npm token to GitHub Secrets as NPM_TOKEN.

Maintenance

Updating Rules

1. Edit rule files in rules/base/ or rules/stacks/
2. Update version in package.json
3. Build and publish
4. Users can update with resit update

Adding New Features

1. Create new command in src/commands/
2. Register command in src/cli.ts
3. Update README
4. Build and publish

Contributing

Adding New Stacks

We welcome contributions for new stack support! To add a new stack:

1. Create a rule file in rules/stacks/[stack-name].md
2. Follow the existing format and structure
3. Add detection logic to StackResolver
4. Update this README
5. Submit a pull request

Improving Rules

To improve existing rules:

1. Edit the relevant markdown file
2. Ensure rules are clear and actionable
3. Test with AI assistants
4. Submit a pull request

License

MIT

Support

For issues, questions, or contributions, please visit the project repository.

Roadmap

• [ ] Support for more stacks (Vue.js, Angular, Django, etc.)
• [ ] Custom rule templates
• [ ] Rule versioning and migration
• [ ] Integration with more AI tools
• [ ] Rule validation and linting
• [ ] Interactive rule customization
• [ ] Team-specific rule overrides