project-rules-generator 0.3.0

A standard for defining project rules and skills for AI agents.

Project Rules Generator

---

The Problem

Every AI agent you use — Claude, Cursor, Windsurf, Copilot — starts every conversation knowing nothing about your project.

You explain your stack. Again. You correct the same bad patterns. Again. You watch it generate code that ignores your architecture. Again.

The AI isn't dumb. It's context-blind.

---

The Solution

Project Rules Generator (PRG) builds a persistent intelligence layer for your project — rules, skills, and patterns — that every AI agent reads automatically.

Run it once. Every future AI session starts with project context: your stack, your conventions, your architecture, your do's and don'ts.

cd your-project
prg init .

That's it. Your .clinerules/ is now the memory your AI agents never had.

---

What Gets Generated

.clinerules/
├── rules.md              ← Your coding conventions (tech-specific, auto-detected)
├── constitution.md       ← Non-negotiable principles ("never do X in this project")
├── clinerules.yaml       ← Skill index for agents that support it
└── skills/
    ├── project/          ← AI-generated workflows tailored to YOUR project
    ├── learned/          ← Reusable patterns, shared across projects
    └── builtin/          ← Battle-tested best practices, bundled

Project Lifecycle Generators (Optional):

• spec.md: High-level Product Specifications and constraints (Goals, Stories).
• DESIGN.md: Phase 1 Architecture Document detailing technical integrations.
• PLAN.md & TASKS.json: Phase 2 AI-driven granular task decomposition.

Example rules.md output for a FastAPI project:

## FastAPI Rules (High Priority)
- Use async/await for ALL I/O — never block the event loop
- Pydantic models for every request/response body, no raw dicts
- Use Depends() for injection — never pass dependencies manually

## Testing Rules
- pytest fixtures for all setup; parametrize for edge cases
- Mock at boundaries only (APIs, DB) — never internal logic

No templates. No hand-holding. Generated from your actual project.

---

Quick Start

No API key needed — PRG works offline from your README and file structure:

pip install -e .
prg init .

With a free API key — LLM-generated skills and richer analysis:

export GROQ_API_KEY=gsk_...   # free at console.groq.com
prg analyze . --ai

Full autopilot or granular workflow — analyze, design, plan, code, commit, repeat:

prg analyze . --incremental            # 3-5x faster subsequent runs
prg design "Add OAuth2 login"          # Two-Stage Planning
prg autopilot . --provider anthropic   # Full automation loop

---

The 3-Layer Skill System

Skills are ranked by specificity. More specific always wins:

Layer	Location	What It Contains	Written by	Priority
Project	.clinerules/skills/project/	Auto-generated by prg analyze from this project's README + context	README flow	Highest
Learned	~/.project-rules-generator/learned/	Reusable skills captured explicitly — default target of --create-skill	--create-skill (default)	Medium
Builtin	~/.project-rules-generator/builtin/	Universal patterns (mypy, git, Python idioms)	--scope builtin	Lowest

A project-level skill overrides the global one. Your patterns win.

Skill scope routing:

• prg analyze → writes to project/ (project-context-aware, not reusable)
• --create-skill → writes to learned/ by default (explicit capture = reusable)
• --create-skill --scope builtin → writes to builtin/ for universal patterns

---

AI Providers

PRG auto-detects the best available provider from your environment. Set one key, or set several — it routes intelligently.

Provider	Model	Best For	Key
Anthropic	Claude Sonnet 4.6	Highest quality rules & skills	ANTHROPIC_API_KEY
OpenAI	GPT-4o-mini	Solid all-rounder	OPENAI_API_KEY
Gemini	Gemini 2.0 Flash	Fast + high quality	GEMINI_API_KEY
Groq	Llama 3.1 8b	Free tier, fastest	GROQ_API_KEY

No provider? PRG still works — README + file structure analysis is free and surprisingly smart.

prg providers list       # See what's configured
prg providers test       # Live latency check
prg providers benchmark  # Side-by-side quality ranking

---

All Features & Commands

🔍 1. Analysis & Generation

prg init .                                    # First-run wizard: detect stack, generate rules
prg analyze .                                 # Regenerate from README + file structure
prg analyze . --ai                            # AI-powered analysis (LLM-generated skills)
prg analyze . --incremental                   # Update only what changed (3–5x faster)
prg analyze . --constitution                  # Also generate constitution.md

🧠 2. Two-Stage Planning & Specs

prg design "Add OAuth2 login"                 # Stage 1: Generates DESIGN.md architecture document
prg plan   "Add OAuth2 login"                 # Stage 2: Generates PLAN.md + TASKS.json implementation plan
        # Note: spec.md is auto-generated if absent during planning

🛠️ 3. Skill Management

prg analyze . --create-skill "auth-flow" --ai             # Create a global learned/ reusable skill
prg analyze . --create-skill "mypy-types" --scope builtin # Create a universal builtin/ skill
prg skills list --all                                     # List project + learned + builtin skills
prg skills validate my-skill                              # Run quality checker (score must be ≥ 90)

🤖 4. Autonomous Orchestration

prg agent "fix a bug"                         # Smart Orchestration (Maps generic text to an exact skill)
prg review PLAN.md                            # AI Self-Review mode (Generates CRITIQUE.md scorecard)
prg autopilot .                               # Full autonomous loop (discover → plan → code → commit)

(Note: The Lifecycle Manager prg manager . is also theoretically available for complete setup → verify → execute → report cycles).

---

How Analysis Works

prg analyze . --ai
        │
        ▼
  Read README + file structure
        │
        ▼
  Detect tech stack (45+ technologies)
  fastapi · react · pytest · sqlalchemy · docker · ...
        │
        ▼
  AIStrategyRouter
  ┌─────────────────────────────────────────┐
  │  Has API key?  →  CoworkStrategy (LLM)  │
  │  Has README?   →  READMEStrategy        │
  │  Fallback      →  StubStrategy          │
  └─────────────────────────────────────────┘
        │
        ▼
  Quality gate (score ≥ 90) → auto-retry if needed
        │
        ▼
  .clinerules/rules.md + skills/

Rules are scored before they're written. Generic filler never makes it through.

---

Installation

git clone https://github.com/Amitro123/project-rules-generator
cd project-rules-generator
pip install -e .
prg --version

Requirements: Python 3.8+, Git

---

Contributing

# Run tests
pytest

# Format (required before commit)
black . && ruff check . && isort .

1. Fork → feature branch → pytest → black . → PR
2. Follow conventional commits: feat:, fix:, refactor:

See CLAUDE.md for architecture notes and docs/architecture.md for full diagrams.

---

License

MIT — see LICENSE.

---

Full version history: CHANGELOG.md · Architecture: docs/architecture.md · Feature deep-dives: docs/features.md