agentic-rules-writer

name	agentic-rules-writer
description	Generate a rules file for any AI coding agent. Interactive setup that scans installed skills, asks about workflow preferences, and writes a tailored instruction file for Claude Code, Cursor, Windsurf, Copilot, Gemini, Roo Code, or Amp. Supports global (user-level), project team-shared, and project dev-specific scopes.
argument-hint	[optional: agent-name e.g. claude, cursor, windsurf]

Agentic Rules Writer

Generate a tailored rules/instruction file for any AI coding agent. Runs an interactive questionnaire, scans installed skills at runtime, and writes the output in the correct format and location for the chosen agent and scope.

When to Use

• Setting up a new AI coding agent for the first time
• Creating team-shared project rules for consistent behavior across developers
• Adding personal dev-specific rules to a project (gitignored)
• After installing new skills to update the rules file with skill references

Quick Start

/agentic-rules-writer claude
/agentic-rules-writer cursor
/agentic-rules-writer              # asks which agent

---

Phase 1: Agent Selection

If $ARGUMENTS is provided, map it to an agent from the table below (case-insensitive, partial match OK — e.g. "wind" matches Windsurf). If no argument or no match, ask the user to pick.

Agent	Format Notes
Claude Code	Plain Markdown, keep under 200 lines
Cursor	Requires YAML frontmatter: alwaysApply: true, .mdc extension
Windsurf	Plain Markdown, enforce under 12,000 characters
GitHub Copilot	Plain Markdown
Gemini CLI	Plain Markdown
Roo Code	Plain Markdown
Amp	Same format as Claude Code

See references/agent-targets.md for full details on each agent's format, paths, limits, and testing instructions.

---

Phase 2: Scope Selection

Ask the user which scope to generate rules for:

Scope	Description	Typical Path (Claude Code example)
Global	User-level rules applied to every project. Personal workflow preferences.	~/.claude/CLAUDE.md
Project (team-shared)	Committed to the repo. Shared conventions the whole team follows.	.claude/rules/team-rules.md
Project (dev-specific)	Local to this dev, gitignored. Personal preferences layered on top of team rules.	.claude/rules/dev-rules.md

See references/agent-targets.md for the exact path for each agent + scope combination.

If the target file already exists, ask the user:

1. Overwrite — replace entirely with generated content
2. Merge — append generated content below existing content (separated by ---)
3. Abort — cancel and leave the file untouched

---

Phase 3: Workflow Questionnaire

Ask questions one at a time, wait for the user's answer before proceeding to the next. Accept short answers, numbers, or the exact option text.

Which questions to ask depends on the scope:

Question	Global	Team-shared	Dev-specific
Q1. Primary stack	Yes	Yes	Skip
Q2. Planning discipline	Yes	Skip	Yes
Q3. Testing philosophy	Yes	Yes	Skip
Q4. Branch conventions	Yes	Yes	Skip
Q5. Commit conventions	Yes	Yes	Skip
Q6. Code quality bar	Yes	Yes	Skip
Q7. Autonomy level	Yes	Skip	Yes
Q8. Task tracking	Yes	Skip	Yes
Q9. Self-improvement	Yes	Skip	Yes
Q10. Additional comments	Yes	Yes	Yes

Rationale: Team-shared rules cover technical standards the whole team agrees on (stack, testing, branching, commits, quality). Dev-specific rules cover personal workflow preferences (planning style, autonomy, task tracking, self-improvement). Global includes everything.

See references/questionnaire.md for the full question reference with descriptions, option mappings, and example outputs.

Questions

Q1. Primary stack Options: PHP+Symfony / TypeScript+React / Python+Django / Go / Rust / Java+Spring / Other (If "Other", ask them to specify.)

Q2. Planning discipline Options:

• Always plan first — enter plan mode for every task
• Plan for 3+ steps — plan mode only for multi-step tasks
• Minimal planning — jump straight to implementation

Q3. Testing philosophy Options:

• Strict TDD — write tests before implementation, always
• Test alongside — write tests and code together
• Test after — implement first, add tests after
• Minimal — only test critical paths

Q4. Branch conventions Options:

• Type prefix — feature/, fix/, chore/, hotfix/ + description
• Ticket prefix — PROJ-123/description or PROJ-123-description
• Flat descriptive — just a kebab-case name, no prefix
• Other — ask them to specify

Q5. Commit conventions Options:

• Conventional commits — feat:, fix:, chore:, etc.
• Ticket prefix — PROJ-123: description
• Freeform — no enforced format

Q6. Code quality bar Options:

• Staff engineer rigor — exhaustive edge cases, defensive coding, thorough documentation
• Senior pragmatic — solid quality with practical trade-offs
• Ship fast — working code with minimal ceremony

Q7. Autonomy level Options:

• Autonomous — fix bugs, failing CI, lint errors without asking
• Semi-autonomous — ask before destructive or risky operations only
• Conservative — confirm everything before acting

Q8. Task tracking Options:

• Todo files — maintain a TODO.md or similar tracking file
• Built-in tasks — use the agent's built-in task/todo system
• No formal tracking — just work through tasks naturally

Q9. Self-improvement Options:

• Lessons file — maintain a lessons-learned file, update after corrections
• No formal tracking — learn implicitly from context

Q10. Additional comments Free-text. Ask: "Any additional rules, preferences, or comments you'd like included?"

• If the user provides text, include it verbatim in an "## Additional Rules" section at the end of the generated file
• If the user says "no" or skips, omit the section entirely

---

Phase 4: Skill Scanning

Scan for installed skills at runtime. Check these locations:

~/.claude/skills/*/SKILL.md          # user-level skills
.claude/skills/*/SKILL.md            # project-level skills
~/.claude/plugins/*/skills/*/SKILL.md  # marketplace plugins

For each found skill:

1. Read the YAML frontmatter to extract name and description
2. Build a mapping: When [situation matching description] -> use /skill-name

Also detect which code-virtuoso skills are NOT installed and build a recommendations list. The full code-virtuoso skill catalog:

Skill	Description
design-patterns	26 GoF design patterns with multi-language examples
refactoring	89 refactoring techniques and code smells
solid	5 SOLID principles for OO design
debugging	Systematic debugging methodology and root cause analysis
clean-architecture	Clean Architecture, Hexagonal Architecture, and DDD fundamentals
testing	Testing pyramid, TDD schools, test doubles, and testing strategies
api-design	REST and GraphQL API design principles and evolution strategies
security	OWASP Top 10, auth patterns, and secure coding practices
symfony	38 Symfony component references (PHP projects)
agentic-rules-writer	This skill (already installed)

---

Phase 5: Assemble and Write

Generate the rules file content from the questionnaire answers. Structure depends on scope.

Global Scope Structure

# Global Rules

## Workflow
[Planning rules from Q2]
[Autonomy rules from Q7]
[Re-plan rule: "If an approach fails or hits unexpected complexity, stop and re-plan immediately"]

## Code Quality
[Quality bar from Q6]
[Testing rules from Q3]
[Stack conventions from Q1]
[Elegance check: "For non-trivial changes, pause and ask: is there a more elegant way?"]

## Version Control
[Branch rules from Q4]
[Commit rules from Q5]

## Task Management
[Tracking from Q8]
[Self-improvement from Q9]

## Core Principles
- Simplicity first — make every change as simple as possible
- Root causes only — no temporary fixes, find and fix the real problem
- Minimal blast radius — touch only what's necessary
- Prove it works — never mark done without verification

## Skills
[Auto-generated from Phase 4 scan]
When [situation] -> use /skill-name
...

## Agent Roles
[If any role skills (product-manager, architect, backend-dev, frontend-dev, qa-engineer, project-manager) are detected during Phase 4 scan, list them here with their responsibilities. If no role skills are installed, omit this section entirely.]

## Recommended (not installed)
- Install [skill] from krzysztofsurdy/code-virtuoso — [what it helps with]

Project Team-Shared Structure

# Project Rules

## Stack & Conventions
[Stack conventions from Q1]
[Quality bar from Q6]

## Testing
[Testing rules from Q3]

## Version Control
[Branch rules from Q4]
[Commit rules from Q5]

## Core Principles
- Simplicity first — make every change as simple as possible
- Root causes only — no temporary fixes, find and fix the real problem
- Minimal blast radius — touch only what's necessary
- Prove it works — never mark done without verification

Project Dev-Specific Structure

# Dev Rules

## Workflow
[Planning rules from Q2]
[Autonomy rules from Q7]

## Task Management
[Tracking from Q8]
[Self-improvement from Q9]

Agent-Specific Formatting

Apply these transformations before writing:

Cursor — Wrap entire content in YAML frontmatter:

---
alwaysApply: true
---

[content here]

Windsurf — Check character count. If over 12,000, condense sections (remove examples, shorten descriptions) until under limit. Add a comment at the top: <!-- Windsurf rules — kept under 12,000 chars -->.

Claude Code / Amp (global) — Keep under 200 lines. Add a note at the end: For project-specific rules, use .claude/rules/*.md files.

All others — Write plain Markdown as-is.

Rule Generation Examples

These examples show how questionnaire answers map to generated rules.

Q2 = "Plan for 3+ steps" generates:

- Enter plan mode for any task that requires 3 or more steps
- For simple changes (single file, obvious fix), proceed directly

Q3 = "Strict TDD" generates:

- Write failing tests before any implementation code
- Red-green-refactor cycle for every change
- Never skip the refactor step

Q4 = "Type prefix" generates:

- Name branches with type prefix: feature/, fix/, chore/, hotfix/
- Use kebab-case for the description part
- Example: feature/add-user-auth, fix/payment-timeout

Q5 = "Conventional commits" generates:

- Use conventional commit format: feat:, fix:, chore:, docs:, refactor:, test:
- Keep subject line under 72 characters
- Use body for context when the change is non-trivial

Q6 = "Senior pragmatic" generates:

- Write clean, well-structured code with practical trade-offs
- Handle edge cases that are likely to occur in production
- Document non-obvious decisions with brief inline comments

Q7 = "Semi-autonomous" generates:

- Fix lint errors, type errors, and failing tests without asking
- Ask before: force-pushing, deleting branches, modifying CI/CD, running destructive commands
- Ask before making architectural changes not covered by the current task

Q9 = "Lessons file" generates:

- After any correction or mistake, update the lessons-learned file
- Review lessons file at the start of each session

---

Phase 6: Confirmation

After writing the file:

1. Display the full generated content to the user
2. Show the file path where it was written
3. Show the line count and character count
4. If any agent-specific limits were applied (e.g., Windsurf char limit, Claude line limit), mention what was condensed
5. Offer: "Would you like to edit anything before we're done?"

---

Error Handling

• If a target directory doesn't exist, create it
• If the user aborts during the questionnaire, discard all progress — don't write a partial file
• If skill scanning finds no skills, skip the Skills section entirely and include the full recommendations list
• For project scopes, verify you are inside a git repository before writing