Override Management

Override Skill

When to use

Use when creating or managing project-level overrides for shared skills, rules, commands, or guidelines — customizing .augment/ content without modifying originals.

Do NOT use when:

• Changing shared content that should affect all projects (edit src/ directly)
• Creating new skills from scratch (use skill-writing skill)

Purpose

The .augment/ directory is delivered as a Composer package and is read-only at project level. It contains shared skills, rules, commands, guidelines, and templates that work across all projects.

The agents/overrides/ directory is project-specific and lives in the project's own repository. It customizes shared behavior for a particular codebase without modifying the originals.

Critical rule: Never edit files in .augment/ to fix a project-specific need. Changes to .augment/ affect ALL projects. Use overrides instead.

Procedure: Create an override

Before creating an override, understand the original:

1. Read the original from .augment/{type}/{name} — understand its purpose, structure, and behavior.
2. Check for existing overrides in agents/overrides/{type}/ — avoid duplicates.
3. Identify what needs changing — only override the specific behavior that differs for this project.

When loading any skill, rule, or command:

1. Load the original from .augment/{type}/{name}
2. Check for override in agents/overrides/{type}/{name}
3. If override exists, read its Mode header:
   • extend — Apply the original first, then layer the override on top (additive)
   • replace — Ignore the original entirely, use only the override

Directory Structure

agents/overrides/
├── rules/           ← Override .augment/rules/*.md
│   └── .gitkeep
├── skills/          ← Override .augment/skills/*/SKILL.md
│   └── .gitkeep
├── commands/        ← Override .augment/commands/*.md
│   └── .gitkeep
├── guidelines/      ← Override .augment/guidelines/**/*.md
│   └── .gitkeep
└── templates/       ← Override .augment/templates/*.md
    └── .gitkeep

File Naming Convention

Override files must match the original filename exactly:

Skills are flattened: the original lives in a directory (skills/{name}/SKILL.md), but the override is a single file (skills/{name}.md).

Guidelines are flattened with a prefix: docs/guidelines/php/controllers.md → guidelines/php-controllers.md.

Templates keep their original filename: templates/roadmaps.md → templates/roadmaps.md.

Override File Format

Every override file must have this header:

# Override: {Type} — {name}

> Override for `.augment/{path-to-original}`

---
**Mode:** `extend`
**Original:** `.augment/{path-to-original}`
---

Mode: extend

• The original is loaded first
• The override adds, modifies, or removes specific parts
• Reference original sections by heading name
• Only write what changes — everything else stays as-is

Mode: replace

• The original is completely ignored
• The override is the sole source of truth
• Must be self-contained and complete

When to Create Overrides

When NOT to Create Overrides

• Don't override to fix bugs in the shared package — fix the original in the .augment/ package repo instead
• Don't override for temporary changes — use branch-specific notes instead
• Don't create empty overrides — only create when there's actual content
• Don't duplicate the original — extend mode should only contain the delta

Checking for Overrides (Agent Behavior)

Before executing any skill, rule, or command, agents must:

1. Note the original path (e.g., .augment/skills/eloquent/SKILL.md)
2. Check if agents/overrides/skills/eloquent.md exists
3. If it exists, read the Mode header
4. Apply accordingly:
   • extend → Load original, then apply override additions/changes
   • replace → Skip original, use override only

Templates

Override templates are in .augment/templates/overrides/:

Related

• Commands: /override-create, /override-manage
• Skill: agent-docs-writing (documentation hierarchy)
• Templates: .augment/templates/overrides/

Validate

• Verify the override file exists at the correct path in agents/overrides/.
• Confirm the override actually takes effect (test the behavior it modifies).
• Check that the original in .augment/ is not modified.

Output format

1. Override file in agents/overrides/ matching the original's structure
2. Summary of what was overridden and why

Gotcha

• Overrides are invisible to other projects — only the current project sees them.
• Replace mode discards the original entirely — use extend mode unless you need a full rewrite.
• If the override stops working after a package update, the original's structure likely changed.

Do NOT

• Do NOT create overrides for things that should be changed in the original.
• Do NOT use replace mode when extend mode is sufficient.

Auto-trigger keywords

• override
• project override
• extend skill
• replace skill