Metadata-Version: 2.4
Name: project-rules-generator
Version: 0.3.0
Summary: A standard for defining project rules and skills for AI agents.
Author-email: Amitro123 <amitrosen4@gmail.com>
Project-URL: Homepage, https://github.com/Amitro123/project-rules-generator
Project-URL: Repository, https://github.com/Amitro123/project-rules-generator
Project-URL: Changelog, https://github.com/Amitro123/project-rules-generator/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/Amitro123/project-rules-generator/issues
Keywords: ai,agents,rules,skills,scaffolding,claude,cursor,windsurf
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pathspec>=0.11.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: watchdog>=3.0.0
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.8.6; extra == "gemini"
Requires-Dist: google-genai>=0.2.0; extra == "gemini"
Provides-Extra: groq
Requires-Dist: groq>=0.4.0; extra == "groq"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
Provides-Extra: llm
Requires-Dist: google-generativeai>=0.8.6; extra == "llm"
Requires-Dist: google-genai>=0.2.0; extra == "llm"
Requires-Dist: groq>=0.4.0; extra == "llm"
Requires-Dist: openai>=1.0.0; extra == "llm"
Requires-Dist: anthropic>=0.20.0; extra == "llm"
Provides-Extra: opik
Requires-Dist: opik>=0.1.0; extra == "opik"
Provides-Extra: all
Requires-Dist: google-generativeai>=0.8.6; extra == "all"
Requires-Dist: google-genai>=0.2.0; extra == "all"
Requires-Dist: groq>=0.4.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.20.0; extra == "all"
Requires-Dist: opik>=0.1.0; extra == "all"
Dynamic: license-file

# Project Rules Generator

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/Tests-580%2B%20Passing-brightgreen.svg)](tests/)

---

## 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.

```bash
cd your-project
prg init .
```

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

---

## What Gets Generated

```text
.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:**

```markdown
## 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:

```bash
pip install -e .
prg init .
```

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

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

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

```bash
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.

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

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

**Requirements:** Python 3.8+, Git

---

## Contributing

```bash
# 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`](CLAUDE.md) for architecture notes and [`docs/architecture.md`](docs/architecture.md) for full diagrams.

---

## License

MIT — see [`LICENSE`](LICENSE).

---

> Full version history: [`CHANGELOG.md`](CHANGELOG.md) · Architecture: [`docs/architecture.md`](docs/architecture.md) · Feature deep-dives: [`docs/features.md`](docs/features.md)
