merge-executor

name	merge-executor
description	Execute delta merges by generating MERGE_PROMPT.md from change proposals. Use when an approved change proposal needs to be applied to the codebase.

Skill: Merge Executor

Read the MERGE_PROMPT.md instruction file generated by the CLI, and merge each delta file from the change proposal into the main documents one by one, ensuring changes are applied accurately.

Trigger Conditions

• User requests AI to execute the merge after running openlogos merge <slug>
• User mentions "execute merge", "merge", "merge the deltas into the main documents"
• User mentions "read MERGE_PROMPT.md and execute"

Prerequisites

1. logos/changes/<slug>/MERGE_PROMPT.md exists (generated by the openlogos merge command)
2. The delta files and target main documents referenced in MERGE_PROMPT.md all exist

If MERGE_PROMPT.md does not exist, prompt the user to run openlogos merge <slug> first.

Core Capabilities

1. Parse merge instructions from MERGE_PROMPT.md
2. Read each delta file and interpret ADDED / MODIFIED / REMOVED markers
3. Precisely locate the corresponding sections in the main document and execute the merge
4. Maintain formatting and style consistency of the main document
5. Output a change summary
6. Stop and wait for human confirmation — After the merge is complete, the AI's role ends. Never run openlogos archive autonomously.

Execution Steps

Step 1: Read Merge Instructions

Read logos/changes/<slug>/MERGE_PROMPT.md and parse:

• Change proposal name and overview
• Each delta file's path, corresponding target main document path, and operation type

Step 2: Merge Each Delta File

Process delta files one by one in the order listed in MERGE_PROMPT.md:

1. Read the delta file: Understand the ADDED / MODIFIED / REMOVED markers and content
2. Read the target main document: Locate the sections that need modification
3. Execute the merge:
   • ADDED: Insert new content at the specified position in the main document
   • MODIFIED: Replace the content of the same-named section in the main document
   • REMOVED: Delete the corresponding section from the main document
4. Output summary: List what modifications were made to the file

Step 3: Output Overall Change Report

After all deltas have been processed, output:

Merge complete:
- [file path 1]: added x sections, modified y sections, deleted z sections
- [file path 2]: ...

Then AI automatically runs git commit (no user confirmation needed, but must inform user):

git add -A
git commit -m "docs(<slug>): merge spec deltas"

Use git add -A instead of git add logos/resources/ to ensure all spec files touched by this merge (including spec/, skills/, CLAUDE.md, AGENTS.md, etc.) are included in the commit.

Then prompt the user with next steps:

✅ Spec documents merged and committed. Next steps:

Step 1: Implement code
Implement business code + test code per the updated logos/resources/ specs.
AI will automatically commit the code changes when done.

Step 2: Run verification (after code is complete)
Run in the project root:
openlogos verify
- PASS → proceed to Step 3
- FAIL → fix the code and re-run verify (no need to re-run merge)

Step 3: Archive (after verification passes)
openlogos archive <slug>

openlogos verify and openlogos archive are human confirmation points — AI must not execute them without explicit user authorization.

Merge Principles

1. Maintain format consistency: Merged content must match the existing format, indentation, and heading levels of the main document
2. Do not alter unrelated content: Only modify the parts specified by the delta; do not reformat the entire document
3. Ask on conflict: If a section referenced by the delta cannot be found in the main document (possibly already modified by another change), pause and ask the user how to proceed
4. Confirm after each file: Show a modification summary after processing each delta file, and wait for user confirmation before processing the next one

Output Specification

• Directly modify the main documents in logos/resources/ (in-place editing)
• Do not modify any files in logos/changes/
• Do not create new files during the merge (unless a delta specifies adding a completely new document)

Best Practices

• Read everything before acting: Read through all delta files and target documents first to understand the full picture, then merge one by one
• MODIFIED is the most error-prone: Section titles may have minor differences (capitalization, spacing) — fuzzy matching is needed
• Preserve change traces: If the main document has a "last updated" timestamp, remember to update it accordingly
• Delta order matters: Requirement document changes should be processed before API document changes to ensure upstream-downstream consistency

Recommended Prompts

The following prompts can be copied directly for AI use:

• Read logos/changes/<slug>/MERGE_PROMPT.md and execute the merge
• Help me merge the add-remember-me changes into the main documents
• Execute the change merge