agentic-rules-writer

# 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](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](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](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

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

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

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