Manage repository conventions

Overview Repository conventions are the house rules your team follows in a codebase. Moxie Docs detects these rules, gives each a stable identity, and keeps them fresh as your repo changes. You can review, add, edit, dismiss, or reset conventions. Your changes affect what you see in the dashboard and what connected AI agents receive.

What you can do

• View conventions with their category, title, summary, examples, and agent guidance
• Add a new convention
• Edit an existing convention
• Dismiss a convention that doesn’t apply
• Reset a convention after a contradiction so the new version can be reviewed

Before you start

• You need workspace owner or admin access to manage conventions.
• Conventions that fall below visibility thresholds may be hidden from agents but still appear in your list for review.

Find conventions

1. In Moxie Docs, go to Docs.
2. Select Conventions. You’ll see a list grouped by category.
3. Select any convention to open its detail page. You’ll see:
   • Title and Category
   • Summary: a plain-language rule with real file or path examples from your repo
   • Agent guidance: short instructions used by AI tools
   • Status: shows if a contradiction is pending review

Add a convention

1. Go to Docs → Conventions.
2. Select Add convention.
3. Fill in:
   • Category: choose the closest match from the list
   • Title: short name for the rule
   • Summary: describe the rule and include concrete examples (file names, paths, or patterns)
   • Agent guidance: one or two short imperative sentences that tell an agent how to apply the rule
4. Select Save. The convention is added with a stable identity and shared with agents.

Edit a convention

1. Go to Docs → Conventions and open the convention.
2. Select Edit.
3. Update Category, Title, Summary, or Agent guidance. Tip: keep examples specific to your repo to avoid confusion.
4. Select Save. Your edit becomes the authoritative version and clears any pending dismissal for that item.

Dismiss a convention Dismiss items that no longer apply to your repo.

1. Go to Docs → Conventions and open the convention.
2. Select Dismiss.
3. Confirm. The convention is removed from agent outputs and your active list. You can re-add it later if needed.

Handle contradictions (reset to review a new version) Sometimes Moxie detects that a newly found version of a rule conflicts with the stored one. When that happens, Moxie keeps the trusted version and marks the item with a pending contradiction for your review.

1. Go to Docs → Conventions and open any item labeled Contradiction pending.
2. Compare the current Summary with the flagged conflicting version shown on the page.
3. Choose one:
   • Keep current: Do nothing. The trusted version remains active.
   • Reset to review new version: Select Reset and then Edit to update the Summary and Agent guidance with the correct rule. Save when done.

Tips for better outcomes

• Prefer specific examples: reference real directories, filenames, or patterns from your repo.
• Keep agent guidance short and directive: e.g., “Use kebab-case for docs file names under /docs.”
• Review after major refactors: conventions may decay or be removed if their evidence disappears; update them to match new structure.

FAQs

• Why do similar items not duplicate? Each convention has a stable identity, so wording changes won’t create duplicates.
• Why is an item hidden from agents? Conventions that lose confidence can fall below a visibility threshold. They remain in your list so you can edit or dismiss them.
• Who can manage conventions? Workspace owners and admins.