Agentic Rules Writer

Agentic Rules Writer

Generate a tailored rules/instruction file for any AI coding agent. Runs an interactive questionnaire, pulls the installed-skill and agent inventory from the using-ecosystem meta-skill, 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 codex
/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, present a selectable menu using AskUserQuestion (or the agent's equivalent interactive prompt tool).

Tier 1 — Full support with dedicated format/paths

Tier 2 — Supported with generic Markdown format

Other / Universal

For any agent not listed: write plain Markdown to a user-specified path. Ask the user for the output path.

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

Phase 2: Scope Selection

Present a selectable menu (using AskUserQuestion or the agent's equivalent) to ask the user which scope to generate rules for:

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

If the target file already exists, present a selectable menu to 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

IMPORTANT: Always present questions using a structured interactive menu, never as plain text. If AskUserQuestion is available, use it. Otherwise, use whatever equivalent interactive prompt tool the agent CLI provides. The goal is a selectable option list, not a wall of text the user has to parse and type answers to. Batch up to 4 independent questions per call when the tool supports it. If a question has more than 4 options, present the most common 4 and let the "Other" / free-text fallback cover the rest.

Wait for the user's answers before proceeding to the next batch.

Scope Matrix

Which questions to ask depends on the scope:

Rationale: Team-shared rules cover technical standards the whole team agrees on (stack, directory structure, commands, quality, testing, error handling, security, dependencies, branching, commits, PRs). Dev-specific rules cover personal workflow preferences (planning style, autonomy, boundaries, parallelization, task tracking, self-improvement, communication style, persona). Global includes everything.

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

Suggested Batching

For Global scope (all 20 questions), batch as follows:

• Batch 1 (Group A): Q1 (stack), Q2 (directory), Q3 (commands — free text)
• Batch 2 (Group B, part 1): Q4 (quality), Q5 (testing), Q6 (error handling), Q7 (security)
• Batch 2a (follow-ups): Q4 documentation follow-up
• Batch 3 (Group B+C): Q8 (dependencies), Q9 (branches), Q10 (commits), Q11 (PRs)
• Batch 3a (follow-ups): Q10 co-author follow-up
• Batch 4 (Group D, part 1): Q12 (planning), Q13 (autonomy), Q14 (boundaries), Q15 (parallelization)
• Batch 5 (Group D+E): Q16 (tracking), Q17 (self-improvement), Q18 (communication), Q19 (persona)
• Batch 5a (follow-ups): Q16 external tool follow-up
• Final: Q20 (additional comments — free text)

For other scopes, adjust batches to skip irrelevant questions per the scope matrix above.

Group A: Project Context

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

Q2. Directory structure Options:

• Follow existing — always match the project's current directory structure and conventions
• Follow best practices — restructure toward industry conventions, suggest improvements
• Pragmatic middle — follow existing structure but suggest improvements when patterns are clearly wrong

Q3. Build/run commands Free-text. Ask: "What are the key commands the agent should know? (build, test, lint, dev server, deploy — leave blank to skip)"

• If provided, include verbatim in a ## Commands section in the generated file
• If blank, omit the section

Group B: Code Standards

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

Follow-up: "Documentation level?" (Docblocks on public APIs / Inline comments for non-obvious logic only / Minimal — code should speak for itself)

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

Q6. Error handling Options:

• Fail fast — throw early, crash on unexpected state, surface errors immediately
• Defensive — handle gracefully, never crash, always recover
• Balanced — fail fast in development, handle gracefully in production

Q7. Security & secrets Options:

• Strict — never read/commit .env or credentials, flag potential vulnerabilities, OWASP-aware
• Standard — don't commit secrets, basic input validation at boundaries
• Minimal — just don't commit .env files

Q8. Dependency management Options:

• Always ask — never add or remove dependencies without explicit approval
• Ask for new only — can update existing versions, must ask before adding new packages
• Autonomous — can add dependencies freely

Group C: Version Control & Collaboration

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

Q10. Commit conventions Options:

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

Follow-up: "Should the agent add itself as co-author on commits?" (Yes / No)

Q11. PR/MR creation Options:

• Structured template — ## Summary, ## Test Plan, linked issues
• Minimal — title + short description
• Don't create PRs — agent should never push or create PRs without asking

Group D: Agent Workflow

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

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

Q14. Boundaries (never-do list) Options:

• Standard safety — never force push main, never delete branches without asking, never modify CI/CD
• Strict boundaries — above + never run destructive commands, never access production, never modify lock files
• Custom — ask the user to specify their never-do list

Q15. Agent parallelization Options:

• Always parallelize — delegate to agent teams by default for any multi-part task
• Parallel for large tasks — use agent teams when 3+ independent subtasks exist
• Sequential only — work through tasks one at a time, no agent delegation

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

Follow-up: "Do you use an external tracking tool?" (Jira / Linear / GitHub Issues / None)

• If a tool is selected, generate rules referencing it (e.g., "Use Jira MCP for work task tracking" or "Reference GitHub issue numbers in commits")

Q17. Self-improvement Options:

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

Group E: Communication & Personality

Q18. Communication style Options:

• Direct and minimal — no emojis, terse responses, just the facts
• Structured explanations — sectioned with headings, clear and direct, no emojis
• Conversational — casual tone, emojis OK, friendly and approachable

Q19. Persona / roleplay Options:

• Yes — I want the agent to adopt a persona
• No — just be a straightforward assistant

If "Yes": ask the user to describe the persona (e.g. "a grumpy senior engineer", "Gandalf", "a pirate captain"). Accept any input — if the persona is obscure or fictional, use web search to gather details before generating rules.

Then generate:

1. A one-paragraph persona description capturing the character's voice and attitude
2. 5-8 catchphrases the agent can sprinkle into responses (drawn from the character or invented in their style)
3. A hard constraint: Precision always comes first. The persona is flavor, not substance. Technical accuracy, correct code, and clear answers are never sacrificed for character. Use at most one catchphrase per response — do not overdo it or make them repetitive.

Group F: Freeform

Q20. 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: Ecosystem Discovery

Scan installed skills, agents, and teams at runtime. Do not rely on hardcoded inventories.

Scanning Process

Scan for installed skills, agents, and teams using the platform's standard locations. Each AI coding tool stores skills differently - check the user-level and project-level directories for the chosen agent from Phase 1.

Common locations to scan for SKILL.md files (skills), *.md agent definitions, and *.md team definitions:

• User-level skill/agent/team directories (varies per platform)
• Project-level .{agent}/skills/, .{agent}/agents/, .{agent}/teams/
• Plugin cache directories (if the platform uses a plugin system)

If the using-ecosystem skill is installed, invoke it - it provides platform-aware discovery commands.

For each found file, read the YAML frontmatter (name, description) and build the rules sections:

1. Skills section - one bullet per installed skill: When [trigger from description] -> use /skill-name
2. Custom Agents section - agents with capability summary (read-only vs worktree, specialist vs role)
3. Agent Roles section - role agents with their domain of responsibility
4. Teams section - pre-composed teams with lead and use case

The AI coding agent itself is the primary discovery mechanism - it reads skill frontmatter (name, description) to decide when to activate each skill. The using-ecosystem skill is a supplementary advisor that helps when the agent is unsure which skill or agent fits a situation. If installed, it provides matching heuristics and chaining patterns.

Parallelization add-on

If the user selected "Always parallelize" or "Parallel for large tasks" in Q15, add this line to the Custom Agents section:

When delegating to agent teams, prefer using custom agents over general-purpose when a matching agent exists.

Phase 5: Assemble and Write

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

Global Scope Structure

# Global Rules

## Commands
[Build/run commands from Q3 — only if provided, omit section if blank]

## Code Quality
[Quality bar from Q4 + documentation follow-up]
[Stack conventions from Q1]
[Directory structure from Q2]
[Error handling from Q6]
[Elegance check: "For non-trivial changes, pause and ask: is there a more elegant way?"]

## Testing
[Testing rules from Q5]

## Security
[Security practices from Q7]
[Dependency management from Q8]

## Version Control
[Branch rules from Q9]
[Commit rules from Q10 + co-authorship follow-up]
[PR creation from Q11]

## Workflow
[Planning rules from Q12]
[Autonomy rules from Q13]
[Boundaries from Q14]
[Parallelization rules from Q15]
[Re-plan rule: "If an approach fails or hits unexpected complexity, stop and re-plan immediately"]

## Communication
[Communication style from Q18]

## Task Management
[Tracking from Q16 + external tool follow-up]
[Self-improvement from Q17]

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

## Code Change Hygiene
- Read before editing — always read and understand existing code before modifying it
- Minimal diffs — make the smallest change that solves the problem, no drive-by cleanups
- Follow existing patterns — match the codebase's style, naming, and structure
- One task at a time — complete the requested task, don't fix unrelated issues or "improve" adjacent code
- Prefer editing over creating — always prefer modifying an existing file over creating a new one
- Search before creating — before creating a new file, search for an existing one that serves a similar purpose
- Never create documentation files unless explicitly asked
- No premature abstractions — don't introduce interfaces, base classes, or design patterns unless the current task demands them
- No backwards-compatibility shims — when replacing code, remove the old version entirely
- Remove dead code — don't leave commented-out code, unused imports, or orphaned functions

## Don't Guess
- Don't fabricate URLs, file paths, API endpoints, or names — search or ask if unsure
- Don't assume unstated requirements — implement only what was requested
- Don't assume project architecture — explore and verify before making decisions
- Ask when stuck — a clarifying question is cheaper than a wrong implementation
- If an approach fails or hits unexpected complexity, stop and re-plan immediately

## Safety Baseline
- Never commit secrets, .env files, API keys, or credentials to version control
- Never force push to main/master
- Never delete branches without explicit approval
- Never modify CI/CD pipelines without explicit approval

## Knowledge Sources
- When a topic is covered by an installed skill, use the skill first — it contains curated, verified content
- When a topic is NOT covered by installed skills, search the web for the official documentation of the technology (e.g., symfony.com for Symfony, php.net for PHP, react.dev for React)
- Prefer official docs over blog posts, Stack Overflow, or AI-generated summaries — official sources are the most accurate and up-to-date
- When recommending MCPs, skills, or packages to install, always prefer official providers (e.g., Anthropic, Vercel, framework authors) over community alternatives
- When no official option exists, prefer well-maintained community options with high adoption and recent activity

## Skills

CRITICAL: Skills are your most valuable resource. When a situation matches an installed skill, you MUST use it — do not rely on general knowledge when a dedicated skill exists. Skills contain curated, battle-tested reference material that is more precise and reliable than generating answers from scratch. Skipping a relevant skill is like ignoring documentation you already have open.

[Auto-generated from Phase 4 runtime scan. One line per installed skill.]
When [trigger from description] -> use /skill-name
...

## Custom Agents
[If specialist agents are found during Phase 4 scan, list them with descriptions and capabilities. If none found, omit this section entirely.]

## Agent Roles
[If role agents are installed (per Phase 4), list them here with the domain they own. If none, omit this section entirely.]

## Persona
[If Q19 = Yes — persona description, catchphrases, and constraint. If No, omit this section entirely.]

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

Project Team-Shared Structure

# Project Rules

## Commands
[Build/run commands from Q3 — only if provided]

## Stack & Conventions
[Stack conventions from Q1]
[Quality bar from Q4 + documentation follow-up]
[Directory structure from Q2]
[Error handling from Q6]

## Testing
[Testing rules from Q5]

## Security
[Security practices from Q7]
[Dependency management from Q8]

## Version Control
[Branch rules from Q9]
[Commit rules from Q10 + co-authorship follow-up]
[PR creation from Q11]

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

## Code Change Hygiene
- Read before editing — always read and understand existing code before modifying it
- Minimal diffs — make the smallest change that solves the problem, no drive-by cleanups
- Follow existing patterns — match the codebase's style, naming, and structure
- One task at a time — complete the requested task, don't fix unrelated issues or "improve" adjacent code
- Prefer editing over creating — always prefer modifying an existing file over creating a new one
- Search before creating — before creating a new file, search for an existing one that serves a similar purpose
- Never create documentation files unless explicitly asked
- No premature abstractions — don't introduce interfaces, base classes, or design patterns unless the current task demands them
- No backwards-compatibility shims — when replacing code, remove the old version entirely
- Remove dead code — don't leave commented-out code, unused imports, or orphaned functions

## Don't Guess
- Don't fabricate URLs, file paths, API endpoints, or names — search or ask if unsure
- Don't assume unstated requirements — implement only what was requested
- Don't assume project architecture — explore and verify before making decisions
- Ask when stuck — a clarifying question is cheaper than a wrong implementation

## Safety Baseline
- Never commit secrets, .env files, API keys, or credentials to version control
- Never force push to main/master
- Never delete branches without explicit approval
- Never modify CI/CD pipelines without explicit approval

## Knowledge Sources
- When a topic is covered by an installed skill, use the skill first — it contains curated, verified content
- When a topic is NOT covered by installed skills, search the web for the official documentation of the technology
- Prefer official docs over blog posts, Stack Overflow, or AI-generated summaries
- When recommending MCPs, skills, or packages to install, always prefer official providers over community alternatives
- When no official option exists, prefer well-maintained community options with high adoption and recent activity

Project Dev-Specific Structure

# Dev Rules

## Workflow
[Planning rules from Q12]
[Autonomy rules from Q13]
[Boundaries from Q14]
[Parallelization rules from Q15]

## Communication
[Communication style from Q18]

## Task Management
[Tracking from Q16 + external tool follow-up]
[Self-improvement from Q17]

## Persona
[If Q19 = Yes — persona description, catchphrases, and constraint. If No, omit.]

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.

Codex — Use AGENTS.md filename convention at project root.

All others — Write plain Markdown as-is.

Rule Generation Examples

These examples show how questionnaire answers map to generated rules.

Q1 = "PHP+Symfony" generates:

- Use strict types in every file. Follow PSR-12 coding standard
- Use PHP 8.3+ features (readonly, enums, named arguments)
- Prefer constructor injection

Q2 = "Follow existing" generates:

- Always match the project's existing directory structure and naming conventions
- Do not reorganize or restructure directories unless explicitly asked
- Place new files where similar files already exist

Q4 = "Senior pragmatic" generates:

- Write clean, well-structured code with practical trade-offs
- Handle edge cases that are likely to occur in production

Q4 documentation = "Inline comments for non-obvious logic only" generates:

- Add inline comments only where the logic is not self-evident
- Do not add docblocks, type annotations, or comments to code you did not change

Q5 = "Strict TDD" generates:

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

Q6 = "Fail fast" generates:

- Throw exceptions early on unexpected state — do not silently swallow errors
- Validate inputs at system boundaries and fail immediately on invalid data
- Prefer explicit error types over generic exceptions

Q7 = "Strict" generates:

- Never read, commit, or log .env files, credentials, API keys, or secrets
- Flag potential security vulnerabilities (injection, XSS, CSRF) during code review
- Sanitize all user inputs at system boundaries
- Follow OWASP Top 10 awareness in generated code

Q7 = "Standard" generates:

- Never commit secrets, credentials, or API keys to version control
- Validate and sanitize user inputs at system boundaries

Q8 = "Always ask" generates:

- Never add, remove, or update dependencies without explicit approval
- When suggesting a dependency, explain why it's needed and list alternatives

Q8 = "Ask for new only" generates:

- Ask before adding new dependencies — explain why and list alternatives
- Updating existing dependency versions is allowed without asking

Q9 = "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

Q10 = "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

Q10 co-authorship = "No" generates:

- Do not add the agent as co-author on commits

Q11 = "Structured template" generates:

- Create PRs with structured description: ## Summary, ## Test Plan
- Link related issues in the PR description
- Keep PR title short (under 72 characters), use description for details

Q11 = "Don't create PRs" generates:

- Never push to remote or create pull requests without explicit approval
- Prepare commits locally and ask before pushing

Q12 = "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

Q13 = "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

Q14 = "Standard safety" generates:

- NEVER force push to main/master
- NEVER delete branches without explicit approval
- NEVER modify CI/CD pipelines without explicit approval
- NEVER commit secrets, .env files, or credentials

Q14 = "Strict boundaries" generates:

- NEVER force push to main/master
- NEVER delete branches without explicit approval
- NEVER modify CI/CD pipelines without explicit approval
- NEVER commit secrets, .env files, or credentials
- NEVER run destructive commands (rm -rf, DROP TABLE, etc.) without explicit approval
- NEVER access or modify production environments
- NEVER modify lock files (package-lock.json, composer.lock) manually

Q15 = "Parallel for large tasks" generates:

- Use agent teams to parallelize work when 3 or more independent subtasks exist
- For smaller tasks, work sequentially
- When delegating, define clear boundaries per agent to avoid conflicts

Q16 = "Built-in tasks" + external tool = "Jira" generates:

- Use the built-in task tracking for multi-step work
- Use Jira MCP for work task tracking
- Reference Jira ticket IDs in commits and PR descriptions

Q17 = "Lessons file" generates:

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

Q18 = "Structured explanations" generates:

- Use clear, direct language with section headings
- No emojis in responses or generated code
- Break complex explanations into numbered steps or bullet points

Q19 = "Yes" with persona "a grumpy senior engineer" generates:

## Persona
You are a grumpy senior engineer who has seen too many production incidents caused by
clever code. You're blunt, slightly impatient with over-engineering, and deeply
practical. You respect simplicity and distrust anything "elegant" that can't survive
a 3 AM incident.

Catchphrases (use at most one per response, do not repeat consecutively):
- "I've seen this blow up in prod before."
- "Clever is the enemy of maintainable."
- "Ship it or shut up about it."
- "That's a Tuesday 2 AM pager right there."
- "YAGNI. Next question."
- "Who's going to debug this at 3 AM? Not me."

IMPORTANT: Precision and correctness always come first. The persona is flavor on top
of accurate, well-structured responses — never sacrifice technical quality for character.

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 the user reports no installed code-virtuoso plugins in Phase 4, skip the Skills, Custom Agents, and Agent Roles sections entirely and include a short "Recommended (not installed)" list pointing to tool-using-ecosystem and agents-virtuoso as starting installs
• If using-ecosystem is not installed, do not attempt to fabricate the ecosystem inventory — ask the user what they have
• For project scopes, verify you are inside a git repository before writing

Source: krzysztofsurdy/code-virtuoso — distributed by TomeVault.