OpenAgentsControl/.opencode/context/core/context-system/operations/organize.md

Organize Operation

Purpose: Restructure flat context files into function-based folder structure

Last Updated: 2026-01-06

---

When to Use

• Migrating from flat structure to function-based
• Cleaning up disorganized context directories
• Splitting ambiguous files into proper categories
• Resolving duplicate/conflicting files

---

8-Stage Workflow

Stage 1: Scan

Action: Scan category for all files and detect structure

Output: List of files with current structure type (flat vs organized)

---

Stage 2: Categorize

Action: Categorize each file by function

Categorization Rules:

• Explains concept? → concepts/
• Shows working code? → examples/
• Step-by-step instructions? → guides/
• Reference data (tables, commands)? → lookup/
• Errors/issues? → errors/

Output: Categorization plan with flagged ambiguous files

---

Stage 3: Resolve Conflicts (APPROVAL REQUIRED)

Action: Present categorization plan and handle conflicts

Format:

Organizing {category}/ (23 files, flat structure)

Clear categorization (18 files):
  concepts/ (8):
    ✓ authentication.md → concepts/authentication.md
  
  examples/ (5):
    ✓ jwt-example.md → examples/jwt-example.md

Ambiguous files (5 - need your input):
  
  [?] api-design.md (contains concepts AND steps)
      → [A] Split: concepts/api-design.md + guides/api-design-guide.md
      → [B] Keep as concepts/api-design.md
      → [C] Keep as guides/api-design.md

Conflicts (2):
  
  [!] authentication.md → concepts/auth.md
      Target already exists (120 lines)
      → [J] Merge into existing
      → [K] Rename to concepts/authentication-v2.md
      → [L] Skip (keep flat)

Select resolutions (A J or 'auto'):

Validation: MUST wait for user input

---

Stage 4: Preview (APPROVAL REQUIRED)

Action: Show preview of all changes

Format:

Preview changes:

CREATE directories:
  {category}/concepts/
  {category}/examples/
  {category}/guides/
  {category}/lookup/
  {category}/errors/

MOVE files (18):
  authentication.md → concepts/authentication.md
  ... (17 more)

SPLIT files (3):
  api-design.md → concepts/api-design.md + guides/api-design-guide.md

MERGE files (2):
  authentication.md → concepts/auth.md (merge content)

UPDATE:
  {category}/README.md
  Fix 47 internal references

Dry-run? (yes/no/show-diff):

Dry-run: Simulates changes without executing

Validation: MUST get approval before proceeding

---

Stage 5: Backup

Action: Create backup before making changes

Location: .tmp/backup/organize-{category}-{timestamp}/

Purpose: Enable rollback if needed

---

Stage 6: Execute

Action: Perform the reorganization

Process:

1. Create function folders
2. Move files to correct locations
3. Split ambiguous files if requested
4. Merge conflicts if requested

---

Stage 7: Update

Action: Update navigation and fix references

Process:

1. Update README.md with navigation tables
2. Fix all internal references to moved files
3. Validate all links work
4. Update "Last Updated" dates

---

Stage 8: Report

Action: Show comprehensive results

Format:

✅ Organized X files into function folders
📁 Created Y new folders
🔀 Split Z ambiguous files
🔗 Fixed N references
💾 Backup: .tmp/backup/organize-{category}-{timestamp}/

Rollback available if needed.

---

Conflict Resolution

Ambiguous Files

File fits multiple categories (e.g., has concepts AND steps)

Options:

• Split into multiple files (recommended)
• Keep in primary category
• User decides which is primary

Duplicate Targets

Target file already exists

Options:

• Merge content into existing file
• Rename to avoid conflict (e.g., -v2)
• Skip (keep in flat structure)

Auto-Resolution

Agent suggests best option based on:

• File size
• Content analysis
• Existing structure

---

Examples

Organize Flat Directory

/context organize development/

Dry-Run First

/context organize development/ --dry-run

Organize Multiple

/context organize development/
/context organize core/

---

Success Criteria

• All files in function folders (not flat)?
• Ambiguous files resolved?
• Conflicts handled?
• README.md created/updated?
• All references fixed?
• Backup created?
• User approved changes?

---

Related

• standards/structure.md - Folder organization rules
• guides/workflows.md - Interactive examples