The Problem

Every developer is using AI to write code. Nobody has a system for governing the output. AI breaks existing code, produces inconsistent patterns, and ignores project conventions. Each session starts from scratch, and the mistakes repeat.

The Solution

RuleStack is a .rules/ directory standard for AI-governed development. Drop governance rules into your project. Your AI assistant reads them. Output stays consistent. Works with Claude, GPT, Copilot, Cursor -- any AI that reads context files.

Quick Start

npx rulestack init

That's it. You now have a .rules/ directory:

.rules/
  core/
    code-preservation.md    # The 12 preservation laws
    ui-tokens.md            # Design token system
    responsive.md           # 5 breakpoints, mobile-first
    ai-communication.md     # COSCO prompt formula
  roles/
    architect.md            # Module boundaries, ADRs
    backend.md              # CQRS, validation, REST
    frontend.md             # Components, state, a11y
    security.md             # OWASP, auth, CSP
    qa.md                   # Test plans, edge cases
    devops.md               # Docker, CI/CD, deploys
  prompts/
    cosco-template.md       # 5-part prompt template
    audit-template.md       # Role-based audit prompt
    build-phases.md         # 4-phase build checklist
  quality/
    performance.md          # Web vitals, bundle budgets
    accessibility.md        # WCAG 2.2 AA checklist
  rulestack.config.json     # Configuration

Usage

# Create .rules/ with the full governance suite
rulestack init

# Core rules only (4 files) — great for getting started
rulestack init --preset minimal

# Run a role-based audit checklist against your project
rulestack audit --role security

# Validate your .rules/ setup and check for issues
rulestack doctor

# See all installed rules
rulestack list

How It Works

1. rulestack init creates a .rules/ directory in your project root.
2. Your AI assistant reads these files as context when working on your code.
3. AI output follows your governance rules -- consistent patterns, no broken code, proper conventions.
4. rulestack audit --role <role> runs a checklist to verify compliance against a specific discipline.

The rules are plain Markdown. No lock-in. No runtime dependency. Your AI reads them, your team reads them, your CI can lint against them.

The COSCO Formula

Every prompt follows five parts: Context, Objective, Scope, Constraints, Output.

[Context]   You are working on a Next.js e-commerce app with Stripe integration.
[Objective] Add a webhook handler for payment.succeeded events.
[Scope]     Only the webhook route — do not modify existing payment logic.
[Constraints] Must validate Stripe signatures. Must be idempotent. No raw SQL.
[Output]    TypeScript file with tests. Explain retry strategy in comments.

Stop writing "make me a webhook." Start writing prompts that produce governed output.

The 12 Preservation Laws

These are the foundation. Every AI session respects them.

| # | Law | Description | |---|-----|-------------| | 1 | No Deletions | Never remove existing code, files, or functionality without explicit instruction. | | 2 | No Modifications | Do not alter working code outside the current task scope. | | 3 | No Renames | File names, function names, and variable names stay as they are unless asked. | | 4 | No Restructuring | Directory structure and module organization are off-limits. | | 5 | No Dependency Changes | Do not add, remove, or upgrade packages without approval. | | 6 | No Style Changes | Respect existing formatting, naming conventions, and patterns. | | 7 | No Scope Creep | Stay within the boundaries of the current request. | | 8 | No Assumptions | If requirements are ambiguous, ask -- don't guess. | | 9 | No Silent Failures | Every error path must be handled and visible. | | 10 | No Magic | No hidden behaviors, implicit side effects, or undocumented conventions. | | 11 | No Regressions | New code must not break existing tests or functionality. | | 12 | No Orphans | Every new file, function, or route must be reachable and referenced. |

Presets

| Preset | Files | Best For | |--------|-------|----------| | minimal | 4 core rules | Personal projects, getting started | | full | 15 rules (all) | Team projects, enterprise, production |

Works With

RuleStack is AI-agnostic. If your tool reads project files for context, it reads your rules.

• Claude (Claude Code, API, Cursor)
• GitHub Copilot
• GPT-4 / ChatGPT
• Any AI that reads project context files

Philosophy

• "The rules are the team." Governance files encode institutional knowledge. New developers -- human or AI -- onboard by reading them.
• "AI output is a draft, not a commit." Always verify. Rules reduce errors; they don't eliminate review.
• "Plan sharp, execute clean." Decide what you're building before you ask AI to build it.
• "First, do no harm." The preservation doctrine. Protect what works. Extend deliberately.

Contributing

Share your rule packs! See CONTRIBUTING.md for guidelines on submitting new rules, presets, and role definitions.

License

MIT