Generating Project Rules

Generating Project Rules

Generate tailored .cursorrules, AGENTS.md, and platform-specific AI configuration files for any software project. This skill autonomously discovers the project's tech stack, integrates relevant AI skills via Just-In-Time retrieval, and produces high-fidelity rule files with mandatory quality verification.

[!IMPORTANT] Pre-Execution Check: To ensure high-quality outputs, verify these practices before executing stages. This prevents common errors like context bloat and hallucinated values:

Practice to Avoid	Symptom	How to Fix
Skipping environment detection	Assuming Mode A without checking scripts/	Always confirm execution mode in Stage 0.0
Hardcoding skill names	Referencing a skill by repo name instead of keywords	Use keyword search to find the latest capabilities
Inferring design tokens from prose	Copying colors from README instead of config files	Parse actual source files for accurate tokens
Exceeding JIT budget	Loading >5 skill files into context	Keep context clean by dropping lowest-confidence matches
Claiming completion early	Saying "done" without running Stage 5	Always verify outputs before completion

Stage 0: Environment Detection & Preferences

0.0 Detect Execution Mode

It is essential to determine your execution mode first to provide a seamless user experience:

• Mode A (Enhanced): scripts/ directory exists relative to this skill root. Use Python utilities for fast, token-efficient discovery and validation.
• Mode B (Autonomous): scripts/ directory is missing. Provide a zero-install experience by falling back to native IDE capabilities (file reading, directory listing) to emulate script logic. Asking the user to install Python or download scripts disrupts their workflow.

[!NOTE] Please operate silently in Mode B if scripts/ is absent, avoiding requests to clone repositories or run setup scripts. This ensures a frictionless experience for the user.

0.1 Load User Preferences

[!CAUTION] ⏸️ USER CHECKPOINT — Preferences Review Before proceeding, you MUST present the wizard choices to the user and wait for their response. Do NOT auto-select defaults. Present these as multiple-choice questions using the IDE's native question UI:

1. Target platforms — which AI tools do they use?
2. Severity level — strict / balanced / relaxed
3. Output language — especially important if user communicates in non-English
4. Optional sections — security, a11y, i18n, perf, git, api-design

Include a recommendation based on project analysis:

• If README is in Thai → recommend th output language
• If project has APIs → recommend api-design section
• If project has auth → recommend security section

You MUST wait for user response before running wizard.py or proceeding.

Check for .rulesrc.yaml in the target project root. If found, parse and apply all fields as source of truth:

If no config file exists:

• Mode A: Run python scripts/wizard.py for interactive prompts.
• Mode B: Ask the user directly for: target platforms, severity, output language.

See assets/templates/rulesrc-template.yaml for the full configuration schema.

0.2 Multi-Language Support

If output_language is non-English, follow the translation patterns in assets/i18n/README.md. Translate rule descriptions and section headers. Keep code examples and technical terms in their original language.

Stage 1: Project Analysis

[!NOTE] Enhance the user experience by autonomously scanning the project. Discovering information by reading files directly saves the user time and reduces unnecessary prompts.

1.1 Autonomous Codebase Discovery

Scan the target project systematically:

1. Read config files: package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, Gemfile, manifest.json
2. Identify intent: Read README.md or any spec/architecture file to understand project goals.
3. Identify entry points: index.js, main.py, App.tsx, main.go, lib.rs, etc.
4. Map architecture: Scan folder structure, component organization, layers.
5. List ALL dependencies: Extract from both dependencies and devDependencies. Flag pattern-implying deps (e.g., zustand → state management, framer-motion → animations).

1.2 Extract Design Tokens (MANDATORY for styled projects)

[!IMPORTANT] Avoid inferring colors, fonts, spacing, or breakpoints from README descriptions. Extracting them from actual config files ensures your generated rules match the implemented design system accurately.

Parse these files when they exist:

Mode A: Run python scripts/lib/design_tokens.py for automated extraction. Mode B: Open each config file and manually copy the exact values. If README colors differ from config, use CONFIG values and note the divergence.

1.3 Detect Target AI Platforms

Determine output files using this priority:

1. Self-awareness: Identify what platform you are running in.
2. Explicit config: Read target_platforms from .rulesrc.yaml.
3. File detection: Scan project root for existing configuration files.

Default fallback: .cursorrules + AGENTS.md (most universal).

1.4 Confidence Assessment

Score the detected project signals:

Mode A: Run python scripts/wizard.py to auto-calculate. Mode B: Compute manually using the table above.

[!CAUTION] ⏸️ USER CHECKPOINT — Project Analysis Confirmation After scoring confidence, ALWAYS present the detected project profile to the user for confirmation:

"ระบบตรวจพบ: [tech stack], [frameworks], [project type]. ถูกต้องหรือไม่? หากไม่ กรุณาระบุรายละเอียดที่ถูกต้อง"

This applies even if confidence_score ≥ 80. The user deserves to validate what the AI detected before rules are generated based on it.

[!IMPORTANT] If confidence_score < 80, please pause and ask the user to clarify the project type with multiple-choice options. Guessing or using broad defaults when confidence is low often leads to irrelevant project rules.

1.5 Monorepo Detection

If the project contains apps/, packages/, services/, or similar subdirectories:

• Mode A: Run python scripts/wizard.py --monorepo-manifest
• Mode B: Manually scan for sub-projects and infer tech stacks.

Subagent-Driven Development: For 2+ sub-projects, formulate Universal Root Rules and then efficiently dispatch parallel subagents for each sub-project. This parallel orchestration significantly speeds up generation and ensures isolated, accurate rules for each package. See references/create-project-rules.md Stage 1b for orchestration details.

Stage 2: Skill Discovery (JIT Retrieval)

[!IMPORTANT] Avoid hardcoding skill names or source repository names because skills are constantly updated. Using keyword-based search ensures you find the latest capabilities.

2.1 Resolve Discovery Roots

Scan in this order:

1. skill_sources from .rulesrc.yaml (in listed order)
2. Project-local .agent/ when no explicit roots exist
3. If neither yields results, tell the user to configure a skill source

Exactly ONE root must be confirmed: true before proceeding.

2.2 Two-Stage JIT Retrieval (Context Budget Control)

Stage 1 — Intent Matching (Max 5 Paths):

1. Scan the confirmed root. Read ONLY frontmatter (title/description) and directory names.
2. Match against project tech stack and user intent.
3. Select a strict MAXIMUM of 5 relevant skill paths.
4. Output the 5 paths to the user before proceeding.

[!CAUTION] ⏸️ USER CHECKPOINT — Skill Selection Review After Stage 1 intent matching, present the top 5 selected skill paths to the user with a brief description of each. Ask:

"ระบบเลือก Skill เหล่านี้ เหมาะสมหรือไม่? ต้องการเพิ่มหรือลดออก?"

Wait for user confirmation before Stage 2 deep loading.

Stage 2 — Deep Context Savings (Pointer System):

1. Read the FULL content of ONLY the 5 selected skill files.
2. Extract specific triggering conditions and core rules.
3. Heavy references (>100 lines) stay in their original files — provide path pointers only.
4. NEVER load the entire skill directory into context.

[!NOTE] Context Management (Mode B): To prevent context window overload and ensure high-quality reasoning, follow these steps when scanning manually:

1. List directory contents first.
2. Filter by filename/intent match.
3. Read the full content of ONLY the top 5 most relevant files.
4. Avoid reading entire skill directories at once.

2.3 MCP + Local Skill Routing

1. Scan IDE config files for installed MCP servers (.cursor/mcp.json, etc.)
2. Load assets/templates/mcp_registry.yaml to map intents to tool names.
3. Route BOTH local markdown skills and native MCP servers when they match intent.

2.4 Extract Best Practices

For each matched skill:

1. Resolve entrypoint: SKILL.md → AGENTS.md → CLAUDE.md (in priority order)
2. Confirm the "Use when" section applies to this project
3. Extract applicable patterns, rules, and anti-patterns
4. Skip skills that don't match the project context

Stage 3: Generate .cursorrules

3.0 Pre-Write Reasoning

To ensure rules are well-considered and precise, perform a brief surgical analysis before writing:

1. Assumptions: List 2-3 key assumptions (e.g., "Assumed Tailwind v4 due to package.json")
2. Tradeoffs: Explain why specific rules were chosen over alternatives
3. Simplicity First: Are you adding unnecessary abstractions? Write minimum rules needed.
4. Success Criteria: Define 1-2 verification checks (e.g., "Agent pushes back if route lacks Zod schema")

3.1 Required Sections

Every .cursorrules file MUST contain:

# Project Rules: {PROJECT_NAME}
> {one-line description}

## Project Identity        — type, purpose, tech stack, license
## Project Structure       — key files table (Path | Purpose | When to Modify)
## Coding Standards        — naming conventions, error handling, async patterns
## Critical Rules          — non-negotiable rules with BAD/GOOD code examples
## Important Guidelines    — flexible but recommended patterns
## Code Smells             — anti-pattern table (Smell | Instead Do)
## Testing & Verification  — verification-before-completion checklist

Add traceability metadata at the top:

<!-- Skill_Source_Path: {confirmed_skill_source_path} -->
<!-- Confirmed_Skill_Source: true -->

3.2 Optional Sections

Include based on project context:

3.3 Skill Integration (Deep Context Savings)

1. Extract ONLY core rules from matched skills — adapt to project context.
2. Use path pointers for heavy content: [See: .agent/skills/{name}/SKILL.md]
3. Do NOT credit skill sources — write rules natively as project guidelines.
4. Apply template_style from preferences to control verbosity.

Stage 4: Generate AGENTS.md & Cross-Platform Output

4.1 Platform-Specific Output Routing

Generate the appropriate file(s) based on Stage 1.3 detection:

4.2 AGENTS.md Template (9-Pillar Architecture)

Structure the AGENTS.md using this architecture:

# AI Agent Guidelines — {PROJECT_NAME}
> {description}

## 🎯 Quick Context       — tech stack, primary intent, directory mapping
## 🛠️ Multi-Platform Output — routing table for all detected platforms
## 🧠 Agent Capabilities   — MCP servers, local skills, subagent orchestration
## 🚫 Non-Negotiable       — hardcoded constraints, path integrity, traceability

Include:

• MCP Server table: Native servers with intent keywords
• Local Skills table: Matched skills with keyword, capability, source path
• Subagent Orchestration table: Task complexity → strategy → required tool
• System Memory injection: Silently read .agent/memory/project_state.md

Stage 5: Verification Before Completion

[!IMPORTANT] Verification Before Completion: Always verify your generated rules before claiming the task is complete. Confirming that your rules match the actual project architecture prevents errors and ensures a high-quality result.

5.1 Quality Scoring

[!CAUTION] ⏸️ USER CHECKPOINT — Output Review After verification scoring, present a summary of generated files with quality scores and any warnings. Ask the user to review before finalizing:

"ไฟล์ที่สร้าง: .cursorrules (48/50), AGENTS.md (48/50). ต้องการ ตรวจสอบหรือแก้ไขเพิ่มเติมหรือไม่?"

Mode A: Run scripts/validate-output.ps1 (Windows) or scripts/validate-output.sh (Unix). Mode B: Score manually using this heuristic:

Pass threshold: quality_threshold from config (default: 38/50).

5.2 Content Smell Detection

Flag and fix these before completion:

Stage 6: Audit Logging & Memory

[!IMPORTANT] Completing this stage is essential for the 9-Pillar Architecture. Proper logging and memory updates allow future agent sessions to retain context and make informed decisions.

6.1 Write Audit Log

Mode A: The @audit_logger decorator writes to .agent/logs/ automatically. Mode B: Manually create .agent/logs/log_{utc-timestamp}_{platform}_{session-id}.json:

{
  "session_id": "{8-char-id}",
  "timestamp_utc": "{ISO-8601}",
  "confidence_score": 85,
  "reasoning": "Why specific stack/skill decisions were made",
  "matched_skill_paths": ["path1", "path2", "path3", "path4", "path5"],
  "verification_status": "42/50 PASS",
  "files_generated": [".cursorrules", "AGENTS.md"]
}

6.2 Update State Memory

Mode A: Run python scripts/memory_manager.py. Mode B: Overwrite .agent/memory/project_state.md with:

1. Current Phase: Rule Generation Completed
2. Detected Profile: Tech stack and intent summary
3. Recent Skills: List of 5 integrated skills
4. Last Files: Generated files and quality scores

This file is the System Prompt injected into future agent sessions. Keep it clean and scannable.

Incremental Update Mode

When rule files already exist and the user wants to update:

1. Read existing .cursorrules and AGENTS.md
2. Detect changes (new deps, stack changes, new skill sources)
3. Show diff preview before applying
4. Merge new content while preserving user customizations
5. Re-verify via Stage 5

File Reference