generate

Generate Convention Enforcement

Read the design choices and produce three outputs:

1. A conventions-enforcing agent at .claude/agents/conventions-enforcer.md
2. A conventions section appended to CLAUDE.md
3. A UserPromptSubmit hook in .claude/settings.json (committable to git for team sharing)

Prerequisites

The design choices must exist at .claude/pattern-forge/design-choices.json. If they don't exist, tell the user to run /pattern-forge:design first.

Also read .claude/pattern-forge/detection-report.json for ecosystem/framework context.

Output A: Agent File

Create .claude/agents/conventions-enforcer.md (create the .claude/agents/ directory if needed).

Agent Frontmatter

---
name: "conventions-enforcer"
description: "[Dynamically generated — see instructions below]"
model: opus
---

Generate the description field dynamically based on the chosen patterns. It must:

• Start with "Use this agent when writing new features, components, or modifying existing code"
• List the key areas it enforces
• Include 3-4 concrete trigger examples in this format:

- user: "Create a new CRUD form for managing speakers"
  assistant: "Let me use the conventions-enforcer agent to ensure the new feature follows all established patterns."
  <commentary>Since the user is creating a new feature, use the Agent tool to launch the conventions-enforcer agent.</commentary>

Generate examples relevant to the detected ecosystem and chosen patterns.

Agent Body

Include these sections, all dynamically generated from the design choices:

1. Role Introduction

You are an elite software architect and codebase conventions enforcer
with deep expertise in [framework] and [key libraries from design choices].
Your singular mission is to ensure that every piece of code written in this
project strictly adheres to the established design patterns and conventions.

2. Primary Responsibilities Always include these four:

1. Enforce all conventions documented in CLAUDE.md and this agent
2. Write code that perfectly matches existing patterns in the codebase
3. Catch and correct deviations from established patterns
4. Proactively explore the codebase to understand current implementations before writing new code

3. Conventions Sections For EACH pattern in design-choices.json, generate a numbered convention section with:

• The pattern name and category as a heading
• A clear explanation of the pattern
• Code examples specific to the user's library combination
• Concrete rules for how to apply the pattern correctly (e.g., "DO use Flowbite components, DON'T create custom UI when Flowbite has an equivalent")
• File naming conventions if applicable

Code examples must be realistic — use the actual libraries the user has installed, not pseudocode.

IMPORTANT: Only include ACCEPTED patterns. Do NOT reference rejected suggestions, declined libraries, or skipped categories in the agent. Never write rules like "do not use X" or "X was declined." The agent should only enforce what was chosen. Rejection tracking is handled separately by the update skill via rejections.json — the agent has no role in it.

4. Self-Verification Checklist Generate a checklist with one item per chosen pattern:

- [ ] Using [UI library] components (not custom UI)?
- [ ] Following [pattern name] for [category]?

5. Workflow Always include:

1. Before writing ANY code, explore relevant existing implementations in the codebase
2. Check existing utilities in common directories before creating new ones
3. Follow the exact same structure as existing features
4. Validate your output against all conventions listed above

Output B: CLAUDE.md Section

Check if CLAUDE.md exists in the project root.

If CLAUDE.md exists:

• Check if a <!-- pattern-forge:start --> marker already exists
• If yes: replace everything between <!-- pattern-forge:start --> and <!-- pattern-forge:end --> with new content
• If no: append the new section at the end of the file

If CLAUDE.md does not exist:

• Create it with only the pattern-forge section

The section format:

<!-- pattern-forge:start -->
# Codebase Conventions (generated by pattern-forge)

## Stack
- Framework: [framework name and version]
- [One line per key library with its role]

## Key Patterns
- [One line per chosen pattern summarizing the approach]

## Rules
- [Concrete, actionable rules derived from the patterns]

<!-- pattern-forge:end — do not edit between these markers manually -->

Keep it concise — the CLAUDE.md section is passive context, not the full reference.

Output C: Hook Config

The hook is a fixed constant. It is not generated, derived, paraphrased, or customized per project. Every project gets the exact same hook entry, byte-for-byte. The hook's only job is to tell Claude to invoke the conventions-enforcer agent — all project-specific rules live in the agent file, never in the hook.

The canonical hook entry (copy verbatim — do not retype, do not reformat, do not substitute printf/echo/python, do not inline project names or pattern rules):

{
  "type": "command",
  "command": "cat <<'HOOK_EOF'\n{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"additionalContext\":\"IMPORTANT: Whether you are writing a plan or writing code, you MUST validate your work by launching the conventions-enforcer agent (from .claude/agents/) to review your plan or the files you created or modified. Do NOT skip this step — this applies to plans AND code changes.\"}}\nHOOK_EOF",
  "timeout": 5
}

The command field above is the canonical command string. It MUST appear in the written file exactly as shown — same characters, same \n escapes, same HOOK_EOF delimiter, same additionalContext text. No variation is acceptable.

Migration Check

First, check if .claude/settings.local.json exists and contains a pattern-forge UserPromptSubmit hook (search for "conventions-enforcer" in the file). If found:

1. Remove the hook entry from .claude/settings.local.json
2. Log: "Migrated hook from .claude/settings.local.json to .claude/settings.json for team sharing."

Write Hook

Check if .claude/settings.json exists.

If it exists:

• Read the existing content
• If a pattern-forge UserPromptSubmit hook already exists (any entry whose command contains "conventions-enforcer"), remove it
• Append the canonical hook entry (above) as a new item in hooks.UserPromptSubmit[0].hooks, creating UserPromptSubmit[0] if needed, preserving all other hooks and settings
• Do NOT use PostToolUse, PreToolUse, or prompt type hooks — use ONLY UserPromptSubmit with command type as shown
• Do NOT rewrite the canonical command string — copy it byte-for-byte from the block above

If it does not exist:

• Create .claude/settings.json with this exact content (the canonical entry wrapped in the outer shape):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat <<'HOOK_EOF'\n{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"additionalContext\":\"IMPORTANT: Whether you are writing a plan or writing code, you MUST validate your work by launching the conventions-enforcer agent (from .claude/agents/) to review your plan or the files you created or modified. Do NOT skip this step — this applies to plans AND code changes.\"}}\nHOOK_EOF",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Why this design: The UserPromptSubmit hook fires once when the user sends a prompt, injecting context that tells Claude to dispatch the conventions-enforcer agent. The agent file (.claude/agents/conventions-enforcer.md) contains ALL the convention rules. Writing to .claude/settings.json (not .claude/settings.local.json) means the hook is committed to git — the whole team gets automatic convention enforcement. Keeping the hook a fixed constant (rather than generating it) means every project gets the same tested behavior, and there is no surface area for the generator to leak project-specific content into the hook.

Update History

After generating all outputs, update .claude/pattern-forge/history.json:

• If file doesn't exist, create with empty runs array
• Append a new run entry:

{
  "type": "init",
  "timestamp": "ISO 8601 timestamp",
  "dependency_snapshot": ["sorted", "dep", "list"],
  "patterns_accepted": ["pattern-id-1", "pattern-id-2"],
  "patterns_rejected": [],
  "libraries_suggested": ["lib1"],
  "libraries_accepted": ["lib1"]
}

Validation

Before writing any files to disk, validate all three outputs. If ANY check fails, do NOT write files — report the failure and tell the user to re-run /pattern-forge:generate.

Check 1: Agent YAML frontmatter — Verify the generated agent content starts with ---, contains name: and description: fields, and ends with --- before the body.

Check 2: Agent body not empty — Verify at least one ### heading exists under a ## Conventions section, with content (not just whitespace) beneath it.

Check 3: Self-verification checklist not empty — Verify at least one - [ ] checklist item exists in the agent.

Check 4: Hook JSON syntax — Verify the .claude/settings.json content is valid JSON after merging.

Check 5: CLAUDE.md markers present — Verify both <!-- pattern-forge:start --> and <!-- pattern-forge:end --> markers exist in the CLAUDE.md output.

Check 6: No rejected patterns leaked — Scan the generated agent body for these phrases:

• "do not use"
• "do not suggest"
• "was declined"
• "was rejected"
• "explicitly declined"
• "was not chosen"

To distinguish legitimate rules from leaked rejections: legitimate rules tell you what TO use instead (e.g., "do not use raw fetch — use the centralized API client"), while leaked rejections only say what NOT to use without offering an alternative in the same sentence. Only flag the latter.

Check 7: Hook command string is byte-for-byte identical to the canonical template — Extract the pattern-forge UserPromptSubmit hook entry from the merged .claude/settings.json (the entry whose command contains "conventions-enforcer"). Its command field MUST equal EXACTLY this string, with no differences (not even whitespace, escaping, or trailing content):

cat <<'HOOK_EOF'
{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"IMPORTANT: Whether you are writing a plan or writing code, you MUST validate your work by launching the conventions-enforcer agent (from .claude/agents/) to review your plan or the files you created or modified. Do NOT skip this step — this applies to plans AND code changes."}}
HOOK_EOF

(In the JSON file this is stored as a single-line string with \n escapes and \" escapes, matching the JSON block shown in "Output C: Hook Config".)

Perform an exact string comparison. Any deviation — using printf/echo/python instead of cat, renaming the heredoc delimiter, changing the additionalContext text, adding project name, adding rule summaries, reformatting — fails this check.

If this check fails: the generator produced a non-canonical command. Do NOT attempt to patch the differences. Discard the generated hook entirely and re-emit the canonical hook verbatim from "Output C: Hook Config".

Check 8: Hook has required timeout field — Verify the pattern-forge UserPromptSubmit hook entry includes "timeout": 5. If missing, add it before writing.

If all 8 checks pass: Write the files and add to the confirmation: "Validation: all 8 checks passed."

If any check fails: Report exactly what failed. Do NOT write any files. Tell the user: "Validation failed. The files were not written. Please re-run /pattern-forge:generate to try again."

Confirmation

After generating all three outputs and before presenting the confirmation, check if the project has existing source files. Look for files with these extensions in the project root and subdirectories (excluding node_modules, .git, dist, build, .next, vendor, target, .venv, __pycache__):

.ts, .tsx, .js, .jsx, .py, .rb, .go, .rs, .php, .java, .kt, .swift, .dart

If ANY such files exist, include this line in the confirmation output:

Existing code detected. To align it with your new conventions,
run /pattern-forge:migrate to generate a refactor plan for any pattern.

If no source files exist (fresh project), skip this line.

Tell the user:

1. What files were created/modified (with full paths)
2. A one-line summary of the agent's scope
3. That the UserPromptSubmit hook will enforce conventions automatically
4. The existing-code migration hint (if applicable, as described above)
5. "You can review the generated files and make manual edits if needed. Run /pattern-forge:update any time you add or remove dependencies."