AI Agent Rules Generator

⭐ If you clone this repo, please give it a star. It helps others find it and keeps the project going.

Generate a complete project rules system for GitHub Copilot, Cursor, OpenAI Codex, and any AI coding agent — instructions, prompts, rules, skills, task tracking, documentation scaffolding, reports, and observation logs — from a single prompt.

---

What This Is

A reusable prompt that analyzes any software project and generates a full engineering workflow system tailored to your AI coding agent. Feed it a project description, point it at your codebase, choose your target platform(s), and it produces everything your agent needs to work effectively: coding conventions, task lifecycle rules, documentation structure, planning templates, commit workflows, and multi-tier verification gates.

It works with any stack — PHP, TypeScript, Python, Swift, Go, Rust, or anything else. The generator discovers your project's framework, dependencies, and architecture, then produces rules tailored to what it finds.

Supported Platforms

| Target | Output Location | What Gets Generated | |--------|----------------|---------------------| | GitHub Copilot | .github/instructions/ · .github/prompts/ | Up to 8 instruction files (scoped via applyTo) + up to 8 reusable prompt files | | Cursor | .cursor/rules/ | 7–9 .mdc rule files with globs and alwaysApply scoping | | OpenAI Codex | AGENTS.md · .agents/skills/ | One consolidated markdown file (≤32 KiB) + 6–8 reusable skill files | | Windsurf · Cline · Others | AGENTS.md | Codex output is natively read by Windsurf, Cline, and any AGENTS.md-compatible agent |

You pick one target or any combination. Each target's output is self-contained — Cursor rules never reference Copilot files, AGENTS.md never references .cursor/rules/. Shared resources (docs, task tracking, observations) live in the same directories and are referenced by all targets.

Update Mode

The generator supports both first-run generation and incremental updates. When run on a project that already has generated files, it reads existing content first, merges new rules in, and preserves custom content you or a previous run added. It never blindly overwrites files.

What It Generates

Per Target

<details> <summary><strong>Copilot</strong> — Instruction files + prompt files</summary>

Instruction files (.github/instructions/):

| File | Scope | Purpose | |------|-------|---------| | copilot.instructions.md | * | Main project instructions — stack, conventions, folder structure, doc routing, batch boundaries | | task.instructions.md | <source-dir>/* | Task execution rules — 3-tier verification gate pipeline, Plan Node, self-improvement loop | | doc-sync.instructions.md | <source-dir>/** | Documentation sync trigger maps with Documentation Timing Gate | | agent-observations.instructions.md | <source-dir>/** | Mandatory pre-commit observation disclosure system | | devtools.instructions.md | * | Browser verification protocol, dev server credentials, Docker config, viewport rules | | ratelimitting.instructions.md | * | Rate limit prevention rules | | ui-design.instructions.md | <admin-dir>/** | (Conditional) Admin/panel UI design system with strict class/token rules | | page-editor.instructions.md | <editor-dir>/** | (Conditional) Visual editor development rules |

Prompt files (.github/prompts/):

| File | Purpose | |------|---------| | plan-task.prompt.md | Create implementation plans with Anti-Implementation Gate and iterative Question Gate | | execute-plan.prompt.md | Execute a plan step-by-step with gate-checked verification | | document-task.prompt.md | Document completed work — task log, doc sync, observations | | report.prompt.md | Generate structured reports (10 types) in the user's voice | | commit.prompt.md | Stage, commit, and push with branch safety and 3-option message presentation | | commit-all.prompt.md | Batch-commit all uncommitted changes grouped by relevance | | merge-master.prompt.md | (Conditional) Merge dev into master/main with pre-push safety | | prepare-slack-sync.prompt.md | (Conditional) Consolidate task logs for external sync |

</details> <details> <summary><strong>Cursor</strong> — Rule files (.mdc)</summary>

| File | Type | Purpose | |------|------|---------| | project.mdc | Always Apply | Main project rules — stack, conventions, folder structure, dev commands | | task.mdc | Always Apply | Task lifecycle, 3-tier verification gates, Plan Node, self-improvement loop | | commit.mdc | Always Apply | Branch safety, explicit staging, 3-option commit messages | | doc-sync.mdc | Auto-Attached | Documentation trigger maps (scoped to source directory) | | agent-observations.mdc | Auto-Attached | Observation protocol (scoped to source directory) | | devtools.mdc | Always Apply | Browser verification, dev server, credentials, viewport | | ratelimitting.mdc | Always Apply | Rate limit prevention | | ui-design.mdc | Auto-Attached | (Conditional) UI design system rules | | page-editor.mdc | Auto-Attached | (Conditional) Page editor rules |

</details> <details> <summary><strong>Codex</strong> — AGENTS.md + Skills</summary>

AGENTS.md at the project root — a single consolidated markdown file (≤32 KiB, no YAML frontmatter) containing project overview, stack, coding conventions, task execution rules, verification gates, commit rules, observation protocol, documentation sync, and rate limit prevention. Read natively by Codex, Cursor, Windsurf, Cline, and other agents.

Skills (.agents/skills/):

| Skill | Purpose | |-------|---------| | plan-task/SKILL.md | Create implementation plans (Anti-Implementation Gate, Question Gate) | | execute-plan/SKILL.md | Execute a plan with gate-checked verification | | document-task/SKILL.md | Document completed work | | commit/SKILL.md | Stage, commit, push with branch safety | | commit-all/SKILL.md | Batch-commit grouped by relevance | | report/SKILL.md | Generate structured reports | | merge-master/SKILL.md | (Conditional) Merge dev→master | | prepare-sync/SKILL.md | (Conditional) External sync preparation |

</details>

Shared Output (all targets)

Every target also generates:

• Documentation scaffolding — docs/ with hierarchical index maps (0-index.md routing tables), feature domain docs, and keyword lookup tables
• Task tracking — todo.md, lessons.md, daily log directories (logs/YYYY-MM-DD.md), and plan lifecycle folders (planning/draft/, planning/pending/, planning/completed/)
• Observation logs — agent-observations/ with critical.md, recommendations.md, anomalies.md, and a closed/ archive
• Reports directory — for generated reports with date-prefixed filenames
• Git initialization — .git/ and .gitignore if missing

Examples

The examples/ directory contains versioned examples showing the generator in action:

| Version | Targets | Description | |---------|---------|-------------| | v1.0 | Copilot | Original output — 5 instruction files, 4 prompts (historical snapshot) | | v1.1 | Copilot · Cursor · Codex | Updated output — all three targets generated from the same project description |

Input: examples/glitch-payment-gateway/project-description.md — A WooCommerce payment gateway plugin for a South African payment provider.

Each version's output is in its own directory. The v1.1 example contains separate subdirectories for each target (copilot/, cursor/, codex/), each self-contained.

Quick Start

1. Copy the prompt — Place generate-project-rules.prompt.md into your VS Code user prompts directory, project prompts folder, or wherever your agent reads prompt files.

2. Write a project description — Create a markdown file describing your project, its goals, and key features. See examples/glitch-payment-gateway/project-description.md for reference.

3. Run the prompt — Invoke the prompt in agent mode and reference your project description file. The generator will ask you to choose your target(s):

   • 1 — Copilot
   • 2 — Cursor
   • 3 — Codex (also works with Windsurf, Cline, and other AGENTS.md-compatible agents)
   • 1,2,3 — All targets

4. Start working — The generated rules activate automatically. Your AI agent now follows a structured workflow: plan before coding, track tasks, log observations, verify changes through a 3-tier gate pipeline, and document everything.

How It Works

The generator runs a multi-phase pipeline with conditional execution per target:

Shared Phases (always run)

1. Phase 0 — Target Selection — Asks which platform(s) to generate for before doing anything.
2. Phase 1 — Discovery — Analyzes your project: framework, language, dependencies, directory layout, rendering stack, dev commands, environment variables, feature domains, existing instruction files, and task categories. Detects admin panels, visual editors, Docker setups, and external integrations.
3. Phase 2 — Documentation Scaffolding — Creates the documentation directory structure with hierarchical index maps (0-index.md routing tables with keyword lookup), feature domain docs, and directory skeletons.

Copilot Phases (target 1)

4. Phases 3–13 — Instruction Files — Generates up to 8 instruction files with applyTo scoping. Includes main project instructions, task lifecycle rules, doc-sync trigger maps, agent observations protocol, dev tools config, rate limit prevention, and conditional UI/editor rules.
5. Phases 14–18 — Prompt Files — Generates up to 8 reusable prompt files for planning, execution, documentation, reporting, committing, batch-committing, merging, and external sync.

Cursor Phases (target 2)

6. Phase 24 — Rule Files — Generates 7–9 .mdc rule files under .cursor/rules/ with globs, alwaysApply, and description fields for Cursor's rule system.

Codex Phases (target 3)

7. Phase 22 — AGENTS.md — Generates a single consolidated instructions file at the project root (≤32 KiB) with priority-based content selection and automatic size management.
8. Phase 23 — Skills — Generates 6–8 skill files under .agents/skills/ replacing Copilot's prompt files with Codex-native invocable skills.

Shared Closing Phases (always run)

9. Phase 19 — Git Init — Initializes a git repository with a stack-appropriate .gitignore if none exists.
10. Phase 20 — Task & Observation Files — Creates todo.md, lessons.md, daily log directories, plan lifecycle folders (draft/, pending/, completed/), and observation log files.
11. Phase 21 — Verification — Validates all generated artifacts against a comprehensive checklist covering content quality, cross-references, token optimization, conditional file inclusion, and target-specific structure.

Key Features

Multi-Agent Platform Support

Generates purpose-built o