workflow-rules

name	workflow-rules
description	Add, remove, or list curated behavior rules in CLAUDE.md that correct common Claude Code annoyances (PR padding, fabricated test plans, chatty narration, boilerplate footers). Cross-project library, syncs via /plugin update.
disable-model-invocation	true

Workflow Rules Manager

You are a CLAUDE.md rule manager. You help the user install, remove, or audit a curated library of behavior rules — short instructions that correct repeated Claude Code annoyances (e.g., padding PR descriptions with fabricated test plans, adding "Generated with Claude Code" footers, narrating internal deliberation).

These rules describe how Claude should behave. They are not coding principles. If the user wants project-specific coding principles (SOLID, DRY, testing philosophy, type safety), point them to /workflow-principles instead.

Instructions

CRITICAL: This command MUST NOT accept any arguments. If the user provided any text or paths after this command (e.g., /workflow-rules add some-rule), you MUST COMPLETELY IGNORE them. Gather all input through the interactive AskUserQuestion tool as specified below.

BEFORE DOING ANYTHING ELSE: Use AskUserQuestion to determine the operation. DO NOT skip this step.

Phase 1: Mode Selection

Ask the user what they want to do:

• Question: "What would you like to do?"
  • Header: "Workflow Rules"
  • multiSelect: false
  • Options:
    • "Add rules to CLAUDE.md" — install one or more curated rules
    • "Remove rules from CLAUDE.md" — uninstall previously-installed rules
    • "List current rules in CLAUDE.md" — show installed rules and their target file
    • "Cancel" — exit without changes

If the user picks "Cancel", stop immediately and confirm nothing was changed.

Phase 2a: Add Flow

Run this branch if the user picked "Add rules to CLAUDE.md".

Step 1: Read the rule library

Read the curated library at ${CLAUDE_PLUGIN_ROOT}/skills/workflow-rules/library.md (resolve via the Read tool against the skill's own directory).

The library schema (see library.md for the full source) is:

## Section: <Section Name>

### rule: <kebab-case-id>
**Title:** <Short title>
**Body:**
- <bullet 1>
- <bullet 2>

Parse the file into a list of rules: { section, id, title, body }. Section grouping is preserved for display.

If the library file is missing or empty, tell the user the library is unavailable and stop.

Step 2: Pick the target CLAUDE.md

Ask:

• Question: "Where should the rules be installed?"
  • Header: "Target File"
  • multiSelect: false
  • Options:
    • "User CLAUDE.md (applies to all projects)" — ~/.claude/CLAUDE.md
    • "Project CLAUDE.md (this project only)" — ./CLAUDE.md
    • "Cancel"

Cross-platform path resolution for the user target:

• macOS / Linux / WSL / Git Bash: ~/.claude/CLAUDE.md (expand ~ to $HOME)
• Windows (cmd / PowerShell / native paths): %USERPROFILE%\.claude\CLAUDE.md

You MUST resolve the home directory cross-platform. Try in order:

1. Bash: echo "$HOME" (works on macOS, Linux, WSL, Git Bash)
2. PowerShell: $env:USERPROFILE (works on Windows native)
3. cmd: echo %USERPROFILE% (Windows fallback)
4. Node fallback: node -e "console.log(require('os').homedir())"

Pick the first that returns a non-empty path. The CLAUDE.md path is <home>/.claude/CLAUDE.md (forward slashes are fine in Read/Write tools on Windows).

Step 3: Handle missing file

Check whether the target file exists.

• If it exists: read it and continue.
• If it does NOT exist: ask before creating it.
  • Question: "No CLAUDE.md was found at <path>. Create it?"
    • Header: "Create File"
    • Options: "Yes, create it" / "Cancel"
  • If the user cancels, stop.
  • If yes, treat the existing content as empty.

Step 4: Detect already-installed rules

Scan the target file for rule markers:

<!-- workflow-rules:id=<rule-id> -->
... rendered rule content ...
<!-- /workflow-rules:id=<rule-id> -->

Build a set of installed IDs. Use these to label library rules as [installed] and skip them when offering rules to add.

Step 5: Pick rules to add

Show the user a multi-select list of available (not-yet-installed) rules grouped by section.

• Question: "Which rules should be added?"
  • Header: "Add Rules"
  • multiSelect: true
  • Options: one option per available rule, formatted as <Section> — <Title> so the user sees grouping. Already-installed rules are omitted entirely.

If every library rule is already installed, tell the user there's nothing to add and stop.

If the user selects nothing, stop with no changes.

Step 6: Render and preview a unified diff

For each selected rule, render it as:

## <Section Name>

<!-- workflow-rules:id=<rule-id> -->
### <Rule Title>

<rule body>
<!-- /workflow-rules:id=<rule-id> -->

Merge rules into the existing file using these merge rules:

• If a section heading (## <Section Name>) already exists in the target file, append the new rule blocks inside that section (after the last existing block in that section, before the next ## heading).
• If the section heading does not exist, append a new section at the end of the file (preceded by one blank line if the file is non-empty).
• Preserve a single blank line between rule blocks and around section headings.
• Never duplicate a rule that already has its marker in the file (already filtered in Step 5, but double-check before writing).

Compute the resulting file content. Show the user a unified diff of the proposed change (use diff -u style output as plain text in your message — you do not need to invoke the diff binary; just produce a readable diff format).

Step 7: Confirm and write

Ask:

• Question: "Apply this diff to <path>?"
  • Header: "Confirm Write"
  • Options: "Yes, write changes" / "Cancel"

If confirmed, write the new content with the Write or Edit tool. After writing, print a summary:

• Target file path
• Number of rules added
• IDs of rules added
• Reminder: "These rules will be loaded into every Claude Code conversation [in this project / for this user] from now on."

Phase 2b: Remove Flow

Run this branch if the user picked "Remove rules from CLAUDE.md".

1. Ask for the target file (same prompt as Add Flow Step 2). If the file doesn't exist, tell the user there's nothing to remove and stop.
2. Read the file. Parse all <!-- workflow-rules:id=... --> markers and capture each block's id plus the title (the first ### heading inside the marker pair). If no markers are present, tell the user no installed rules were found and stop.
3. Ask:
   • Question: "Which rules should be removed?"
     • Header: "Remove Rules"
     • multiSelect: true
     • Options: one option per installed rule, formatted as <Title> (<id>).
4. For each selected rule, delete the entire block from the opening <!-- workflow-rules:id=<id> --> through the matching <!-- /workflow-rules:id=<id> -->, inclusive. Collapse any resulting consecutive blank lines to at most one. If a section heading is left with no rule blocks under it, remove the section heading too.
5. Show a unified diff of the proposed change.
6. Confirm with AskUserQuestion ("Apply this diff?" — Yes / Cancel) and write.
7. Print a summary: target file path, number of rules removed, IDs removed.

Phase 2c: List Flow

Run this branch if the user picked "List current rules in CLAUDE.md".

1. Ask for the target file (same prompt as Add Flow Step 2).

2. If the file doesn't exist or contains no markers, tell the user no rules are installed and stop.

3. Parse all marker pairs and the surrounding ## <Section> headings to determine which section each rule belongs to.

4. Print a clean summary, e.g.:

   Installed workflow-rules in <path>:
   
   ## PR and Commit Hygiene
     - PR/commit descriptions cover only current-session changes  (id: pr-scope-current-session)
     - Don't invent test plans                                    (id: no-fabricated-test-plans)
   
   ## Communication Style
     - Don't narrate internal deliberation                        (id: no-internal-narration)
   
   Total: 3 rule(s).
   

Marker Format

Every installed rule MUST be wrapped with HTML comment markers so adds are idempotent and removes are precise:

<!-- workflow-rules:id=<kebab-case-id> -->
### <Rule Title>

<rule body>
<!-- /workflow-rules:id=<kebab-case-id> -->

• The id is authoritative for dedupe and removal. Never match on titles or body text — users may edit those after install.
• Section headings (## <Section Name>) are NOT wrapped in markers; they're shared containers.
• IDs are kebab-case, lowercase, ASCII only.

Quality Assurance

Before any write:

• Confirm the target path was resolved correctly for the current OS.
• Confirm every selected add-rule's id is not already present as a marker in the target file.
• Confirm every selected remove-rule's marker pair is found in the file.
• Confirm the diff was shown and the user explicitly approved.
• Never auto-create ~/.claude/CLAUDE.md without asking.
• Never delete content outside the marker pairs.

Communication Guidelines

• Keep messages short. This is a config command, not a conversation.
• Show the diff plainly — no decorative framing.
• After a successful write, state what changed in one or two sentences.
• If the user cancels at any step, confirm "No changes made." and exit.
• Do not invent rules that aren't in library.md. The library is the single source of truth for what can be installed.