Common Git Conflicts in Prompt and Config Files

Conflict markers inside a system prompt or tool schema are not a cosmetic git problem.

They are corrupted control flow: models will treat <<<<<<< as text, JSON parsers will throw, and production can ship nonsense if CI does not catch it.

How to Use This Checklist

Use A to prevent conflicts; B-E when git already stopped a merge/rebase.
Never commit conflict markers. Search the tree before git commit.
Prefer new immutable versions over hand-merging two rewrites of the same live file when both sides are large.
After resolution, run pack validation + a smoke eval before merge.
Pair with Git Workflows for Prompt, Tool, and Config Changes for branch habits that shrink conflict size.

A - Prevention (Do These Continuously)

1. Immutable version files - add system_v4.txt instead of three people rewriting system.txt.
2. Small, short-lived branches - integrate with main daily when editing shared packs.
3. Single-purpose PRs - do not mix huge tone rewrites with tool schema renames.
4. CODEOWNERS + review queue - serialize high-churn policy files when needed.
5. Announce large prompt rewrites - team channel + lock or sequencing agreement.
6. Path-aware CI - fail on conflict marker patterns and invalid JSON in packs.
7. Owner per pack area - one decider for support tone vs security refusals reduces thrash.

B - Detect and Stop the Bleed

8. Read git status - know which files are unmerged.
9. Search markers - rg -n '^(<<<<<<<|=======|>>>>>>>)' agent_pack deploy (or whole repo).
10. Do not run the agent against a working tree that still has markers.
11. Do not "fix" by deleting the other side blindly - understand both intents first.
12. Pause promote/pin updates until the merge is clean and validated.

rg -n '^(<<<<<<<|=======|>>>>>>>)' agent_pack deploy || echo "no markers"

C - Resolve Prompt (Prose) Conflicts

13. Identify both changes - policy A vs policy B; tone vs safety; accidental regenerate.
14. Prefer compose over average - keep both requirements if compatible; write clear combined prose.
15. If incompatible, pick product owner - do not silently average safety down.
16. Remove all marker lines - including =======.
17. Re-read full prompt - ensure no duplicated sections or truncated sentences.
18. Consider cutting a new version file - both sides become history; pin chooses winner.
19. Run gold-set smoke - especially refusal and tool-guidance cases.

Prompt conflict pattern

<<<<<<< HEAD
Refuse to discuss refunds over $50 without approval.
=======
Refuse to discuss refunds over $100 without approval.
>>>>>>> prompt/raise-limit

Resolution is a product decision, not a text-diff aesthetic. Document the chosen limit in the PR.

D - Resolve JSON / YAML Config and Tool Schema Conflicts

20. Parse after edit - python -m json.tool file.json or schema validator.
21. Merge objects by key carefully - watch duplicate tool name entries.
22. Never leave trailing commas or comments if the format forbids them.
23. Breaking field renames - apply dual-support rules; do not ship half of each side.
24. Enum unions - confirm the model-facing enum is intentional, not a naive union of both experiments.
25. Ordering - if loaders depend on list order, make order explicit and reviewed.
26. Pretty-print consistently - huge reorder-only diffs hide real conflicts; agree on formatters.

python -m json.tool agent_pack/tools/tools_v2.json > /dev/null

Schema conflict anti-pattern

Taking required from side A and property names from side B without host dual-read support. That creates guaranteed tool-call failures.

E - Resolve Pin and Flag File Conflicts

27. Pins are pointers - conflicting active.json usually means "who promotes what," not a text merge.
28. Prefer regenerating the pin from the agreed versions after pack resolution.
29. Never average version strings - v2 vs v3 is not v2.5.
30. Keep content hashes honest - recompute if your pin stores hashes.
31. Staging vs prod pins - resolve in the right environment file; do not copy prod into staging by mistake.

F - Finish the Merge Like a Release

32. git add resolved paths - then git status clean of unmerged paths.
33. Marker search green - run the rg check again.
34. Validate packs - JSON, YAML, loader unit tests.
35. Eval or smoke - minimum gold subset for touched agents.
36. PR description notes decisions - especially policy numbers and breaking schema choices.
37. Continue rebase/merge - git merge --continue / git rebase --continue as appropriate.
38. Reviewer re-reads full files - not only the conflict hunk, for prompt files.

G - CI Guard Rails (Copy These Ideas)

"""Fail CI if conflict markers appear under agent packs."""
 
from pathlib import Path
import sys
 
ROOTS = [Path("agent_pack"), Path("deploy")]
MARKERS = ("<<<<<<<", ">>>>>>>", "=======")
 
 
def main() -> int:
    bad: list[str] = []
    for root in ROOTS:
        if not root.exists():
            continue
        for path in root.rglob("*"):
            if not path.is_file():
                continue
            try:
                text = path.read_text(encoding="utf-8")
            except UnicodeDecodeError:
                continue
            for i, line in enumerate(text.splitlines(), 1):
                if line.startswith(MARKERS):
                    bad.append(f"{path}:{i}:{line[:20]}")
    if bad:
        print("conflict markers found:")
        print("\n".join(bad))
        return 1
    print("ok")
    return 0
 
 
if __name__ == "__main__":
    raise SystemExit(main())

Also fail CI on invalid tool JSON and on missing pin fields required by the loader.

Decision Aid: Merge vs New Version

Situation	Prefer
Tiny wording clash on same policy	Hand-merge prose
Two large rewrites of one file	New version file + product pick
Schema add vs schema add (compatible)	Merge keys + validate
Schema rename vs behavior change	Sequence PRs; dual-support
Pin file both changed	Rewrite pin after deciding versions
Generated file both changed	Regenerate from source of truth

FAQs

Why are prompt conflicts worse than code conflicts?

Code conflicts usually fail the compiler or tests. Prompt conflicts can parse fine as text and still ship wrong policy.

Can I accept "ours" or "theirs" wholesale?

Only when you truly intend to drop the other change. For shared policy, that often deletes someone else's required safety line.

What if both sides added different few-shots?

Curate a minimal combined set; large few-shot dumps thrash tokens and hide intent. Redact and eval.

Do formatters cause false conflicts?

Yes. Enforce format on save/CI so diffs are semantic. Reformat both sides to the same style before merging content.

How do coding agents affect conflicts?

They rewrite whole files more often, increasing collide surface. Prefer smaller edits and immutable versions; always re-scan for markers.

Should conflict resolution require a second reviewer?

For safety-critical prompts and tool schemas, yes. Treat the resolution PR as a behavior change.

What about binary or notebook conflicts?

Keep agent packs as text. Do not store canonical prompts in opaque binaries.

Can merge drivers help?

Custom merge drivers are rare and fragile for prose. Process and versioning beat clever drivers for most teams.

We use a prompt hub - still relevant?

Yes if multiple editors can change the same revision or if you mirror hub content into git. Conflict and overwrite risk remains.

What is the fastest safe resolution under incident pressure?

Roll production pin to last known good. Resolve the merge calmly on a branch; do not hot-merge into the live pin mid-incident.

How do we train hires on this?

Run a synthetic conflict drill in onboarding with a deliberate marker file and a required validation script.

Is `=======` always a marker?

At line start during a merge, treat it as a marker. Also search for the angle-bracket forms which are unambiguous.

Git Workflows for Prompt, Tool, and Config Changes - prevent and structure changes
Git & Linux Basics for Agent Developers - rebase/stash basics
Documenting Agent-Specific Conventions for New Team Members - write resolution rules down
Onboarding a New Developer to an Agent Codebase - include conflict drill
Git, Linux CLI & Team Onboarding Best Practices - section habits
Versioning Prompts and Tool Schemas Alongside Code - immutable packs reduce pain
Versioning and Deprecating Agent Tools Without Breaking Agents - schema compatibility
Rollback Strategies When a Deployed Agent Regresses - when merge goes wrong in prod

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Common Git Conflicts in Prompt and Config Files

Conflict markers inside a system prompt or tool schema are not a cosmetic git problem.

They are corrupted control flow: models will treat <<<<<<< as text, JSON parsers will throw, and production can ship nonsense if CI does not catch it.

How to Use This Checklist

Use A to prevent conflicts; B-E when git already stopped a merge/rebase.
Never commit conflict markers. Search the tree before git commit.
Prefer new immutable versions over hand-merging two rewrites of the same live file when both sides are large.
After resolution, run pack validation + a smoke eval before merge.
Pair with Git Workflows for Prompt, Tool, and Config Changes for branch habits that shrink conflict size.

A - Prevention (Do These Continuously)

1. Immutable version files - add system_v4.txt instead of three people rewriting system.txt.
2. Small, short-lived branches - integrate with main daily when editing shared packs.
3. Single-purpose PRs - do not mix huge tone rewrites with tool schema renames.
4. CODEOWNERS + review queue - serialize high-churn policy files when needed.
5. Announce large prompt rewrites - team channel + lock or sequencing agreement.
6. Path-aware CI - fail on conflict marker patterns and invalid JSON in packs.
7. Owner per pack area - one decider for support tone vs security refusals reduces thrash.

B - Detect and Stop the Bleed

8. Read git status - know which files are unmerged.
9. Search markers - rg -n '^(<<<<<<<|=======|>>>>>>>)' agent_pack deploy (or whole repo).
10. Do not run the agent against a working tree that still has markers.
11. Do not "fix" by deleting the other side blindly - understand both intents first.
12. Pause promote/pin updates until the merge is clean and validated.

rg -n '^(<<<<<<<|=======|>>>>>>>)' agent_pack deploy || echo "no markers"

C - Resolve Prompt (Prose) Conflicts

13. Identify both changes - policy A vs policy B; tone vs safety; accidental regenerate.
14. Prefer compose over average - keep both requirements if compatible; write clear combined prose.
15. If incompatible, pick product owner - do not silently average safety down.
16. Remove all marker lines - including =======.
17. Re-read full prompt - ensure no duplicated sections or truncated sentences.
18. Consider cutting a new version file - both sides become history; pin chooses winner.
19. Run gold-set smoke - especially refusal and tool-guidance cases.

Prompt conflict pattern

<<<<<<< HEAD
Refuse to discuss refunds over $50 without approval.
=======
Refuse to discuss refunds over $100 without approval.
>>>>>>> prompt/raise-limit

Resolution is a product decision, not a text-diff aesthetic. Document the chosen limit in the PR.

D - Resolve JSON / YAML Config and Tool Schema Conflicts

20. Parse after edit - python -m json.tool file.json or schema validator.
21. Merge objects by key carefully - watch duplicate tool name entries.
22. Never leave trailing commas or comments if the format forbids them.
23. Breaking field renames - apply dual-support rules; do not ship half of each side.
24. Enum unions - confirm the model-facing enum is intentional, not a naive union of both experiments.
25. Ordering - if loaders depend on list order, make order explicit and reviewed.
26. Pretty-print consistently - huge reorder-only diffs hide real conflicts; agree on formatters.

python -m json.tool agent_pack/tools/tools_v2.json > /dev/null

Schema conflict anti-pattern

Taking required from side A and property names from side B without host dual-read support. That creates guaranteed tool-call failures.

E - Resolve Pin and Flag File Conflicts

27. Pins are pointers - conflicting active.json usually means "who promotes what," not a text merge.
28. Prefer regenerating the pin from the agreed versions after pack resolution.
29. Never average version strings - v2 vs v3 is not v2.5.
30. Keep content hashes honest - recompute if your pin stores hashes.
31. Staging vs prod pins - resolve in the right environment file; do not copy prod into staging by mistake.

F - Finish the Merge Like a Release

32. git add resolved paths - then git status clean of unmerged paths.
33. Marker search green - run the rg check again.
34. Validate packs - JSON, YAML, loader unit tests.
35. Eval or smoke - minimum gold subset for touched agents.
36. PR description notes decisions - especially policy numbers and breaking schema choices.
37. Continue rebase/merge - git merge --continue / git rebase --continue as appropriate.
38. Reviewer re-reads full files - not only the conflict hunk, for prompt files.

G - CI Guard Rails (Copy These Ideas)

"""Fail CI if conflict markers appear under agent packs."""
 
from pathlib import Path
import sys
 
ROOTS = [Path("agent_pack"), Path("deploy")]
MARKERS = ("<<<<<<<", ">>>>>>>", "=======")
 
 
def main() -> int:
    bad: list[str] = []
    for root in ROOTS:
        if not root.exists():
            continue
        for path in root.rglob("*"):
            if not path.is_file():
                continue
            try:
                text = path.read_text(encoding="utf-8")
            except UnicodeDecodeError:
                continue
            for i, line in enumerate(text.splitlines(), 1):
                if line.startswith(MARKERS):
                    bad.append(f"{path}:{i}:{line[:20]}")
    if bad:
        print("conflict markers found:")
        print("\n".join(bad))
        return 1
    print("ok")
    return 0
 
 
if __name__ == "__main__":
    raise SystemExit(main())

Also fail CI on invalid tool JSON and on missing pin fields required by the loader.

Decision Aid: Merge vs New Version

Situation	Prefer
Tiny wording clash on same policy	Hand-merge prose
Two large rewrites of one file	New version file + product pick
Schema add vs schema add (compatible)	Merge keys + validate
Schema rename vs behavior change	Sequence PRs; dual-support
Pin file both changed	Rewrite pin after deciding versions
Generated file both changed	Regenerate from source of truth

FAQs

Why are prompt conflicts worse than code conflicts?

Code conflicts usually fail the compiler or tests. Prompt conflicts can parse fine as text and still ship wrong policy.

Can I accept "ours" or "theirs" wholesale?

Only when you truly intend to drop the other change. For shared policy, that often deletes someone else's required safety line.

What if both sides added different few-shots?

Curate a minimal combined set; large few-shot dumps thrash tokens and hide intent. Redact and eval.

Do formatters cause false conflicts?

Yes. Enforce format on save/CI so diffs are semantic. Reformat both sides to the same style before merging content.

How do coding agents affect conflicts?

They rewrite whole files more often, increasing collide surface. Prefer smaller edits and immutable versions; always re-scan for markers.

Should conflict resolution require a second reviewer?

For safety-critical prompts and tool schemas, yes. Treat the resolution PR as a behavior change.

What about binary or notebook conflicts?

Keep agent packs as text. Do not store canonical prompts in opaque binaries.

Can merge drivers help?

Custom merge drivers are rare and fragile for prose. Process and versioning beat clever drivers for most teams.

We use a prompt hub - still relevant?

Yes if multiple editors can change the same revision or if you mirror hub content into git. Conflict and overwrite risk remains.

What is the fastest safe resolution under incident pressure?

Roll production pin to last known good. Resolve the merge calmly on a branch; do not hot-merge into the live pin mid-incident.

How do we train hires on this?

Run a synthetic conflict drill in onboarding with a deliberate marker file and a required validation script.

Is `=======` always a marker?

At line start during a merge, treat it as a marker. Also search for the angle-bracket forms which are unambiguous.

Git Workflows for Prompt, Tool, and Config Changes - prevent and structure changes
Git & Linux Basics for Agent Developers - rebase/stash basics
Documenting Agent-Specific Conventions for New Team Members - write resolution rules down
Onboarding a New Developer to an Agent Codebase - include conflict drill
Git, Linux CLI & Team Onboarding Best Practices - section habits
Versioning Prompts and Tool Schemas Alongside Code - immutable packs reduce pain
Versioning and Deprecating Agent Tools Without Breaking Agents - schema compatibility
Rollback Strategies When a Deployed Agent Regresses - when merge goes wrong in prod

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Common Git Conflicts in Prompt and Config Files

Search Documentation

Common Git Conflicts in Prompt and Config Files