Skip to main content

ADR-106: Contributor Framework Sync Workflow

Status​

Accepted

Context​

CODITECT has two distinct installation types:

  1. Protected Installation - Read-only copy at ~/Library/Application Support/CODITECT/core/ (macOS) used by all projects via symlinks. No .git directory, files are 0o444/0o555 permissions.

  2. Development Copy - Git-tracked copy at coditect-rollout-master/submodules/core/coditect-core/ used by contributors to make changes.

Contributors need a standardized workflow to:

  • Commit and push changes from the development copy
  • Update the protected installation with the latest version
  • Ensure all project symlinks remain valid

Without a standardized process, contributors risk:

  • Protected installation becoming stale
  • Symlink chains breaking
  • Inconsistent update procedures across contributors

Decision​

Implement /framework-sync command with backing script for contributors to manage the development → protected sync workflow.

Architecture​

DEVELOPMENT (Git-Tracked):
~/PROJECTS/coditect-rollout-master/submodules/core/coditect-core/
    │
    ├── Make changes (edit, create, delete files)
    ├── Test locally
    │
    ▼
/framework-sync (or python3 scripts/framework-sync.py)
    │
    ├── Step 1: Verify contributor setup
    ├── Step 2: Show pending changes (git status, diff)
    ├── Step 3: Stage and commit (conventional format)
    ├── Step 4: Push to origin/main
    ├── Step 5: Update protected installation
    │           ├── Make existing files writable
    │           ├── Remove existing installation
    │           ├── Clone latest from remote (--depth 1)
    │           ├── Remove .git directory
    │           └── Set read-only permissions
    ├── Step 6: Verify sync
    │
    ▼
PROTECTED (Read-Only):
~/Library/Application Support/CODITECT/core/
    │
    ▲
SYMLINKS (all projects):
  ~/.coditect ─────────────────────────┐
  ~/PROJECTS/.coditect ────────────────┼──► Protected Location
  ~/PROJECTS/<project>/.coditect ──────┘
      └── → ../.coditect (relative)

Command Interface​

# Full workflow: review, commit, push, update protected
/framework-sync

# Commit and push only (don't update protected)
/framework-sync --commit-only

# Update protected only (from remote, no local commit)
/framework-sync --update-only

# Provide commit message directly
/framework-sync --message "feat(commands): Add new feature"

# Preview without making changes
/framework-sync --dry-run

# Skip confirmation prompts
/framework-sync --yes

Companion command /symlinks validates and fixes project symlinks:

# Check all project symlinks
/symlinks

# Fix all broken/outdated symlinks
/symlinks --fix

# Fix specific project
/symlinks --fix <project-name>

# Show detailed resolution chains
/symlinks --verbose

Consequences​

Positive​

  1. Standardized workflow - All contributors use same process
  2. Protected installation integrity - Always matches remote main
  3. Read-only enforcement - Protected files can't be accidentally modified
  4. Symlink validation - Projects always point to correct location
  5. Audit trail - Conventional commits track all changes

Negative​

  1. Fresh clone on update - Each update re-clones entire repo (~6000 files)
  2. Remote dependency - Update requires network access to GitHub
  3. Main branch only - Contributors must merge to main before syncing

Neutral​

  1. Contributor-only - Customers use CODITECT-CORE-INITIAL-SETUP.py instead
  2. Platform-specific paths - Protected location varies by OS

Implementation​

Files Created​

FilePurpose
commands/framework-sync.mdCommand documentation
scripts/framework-sync.pyImplementation script
commands/symlinks.mdSymlink validation command
scripts/check-project-symlinks.pySymlink validation script

Platform Paths​

PlatformProtected Location
macOS~/Library/Application Support/CODITECT/core/
Linux~/.local/share/coditect/core/
Windows%LOCALAPPDATA%\CODITECT\core\

Permissions​

File TypePermissionMeaning
Regular files0o444Read-only
Scripts (.py, .sh)0o555Read + execute

HOW TO: Contributor Workflow​

Initial Setup (One Time)​

# 1. Clone coditect-rollout-master with submodules
git clone --recursive https://github.com/coditect-ai/coditect-rollout-master.git
cd coditect-rollout-master

# 2. Run initial setup to create protected installation
python3 submodules/core/coditect-core/scripts/CODITECT-CORE-INITIAL-SETUP.py

# 3. Verify symlinks
/symlinks

Daily Development Workflow​

# 1. Navigate to development copy
cd ~/PROJECTS/coditect-rollout-master/submodules/core/coditect-core

# 2. Make your changes
# - Create/edit agents, commands, skills, scripts
# - Test locally

# 3. Preview what will be synced
/framework-sync --dry-run

# 4. Sync to protected installation
/framework-sync
# Or with a specific commit message:
/framework-sync --message "feat(agents): Add new specialist agent"

# 5. Update parent submodule reference
cd ~/PROJECTS/coditect-rollout-master
git add submodules/core/coditect-core
git commit -m "chore(submodules): Update coditect-core to <commit>"
git push origin main

Quick Sync (After Someone Else Pushed)​

# Pull latest in development copy
cd ~/PROJECTS/coditect-rollout-master/submodules/core/coditect-core
git pull origin main

# Update protected installation only
/framework-sync --update-only
# Check status
/symlinks

# Fix all issues
/symlinks --fix

# Verify
/symlinks

Commit Message Format​

Use conventional commits:

<type>(<scope>): <description>

[optional body]

Co-Authored-By: Claude <noreply@anthropic.com>

Types:

  • feat - New feature (agent, command, skill)
  • fix - Bug fix
  • docs - Documentation only
  • refactor - Code restructuring
  • chore - Maintenance tasks
  • test - Test additions

Examples:

/framework-sync --message "feat(commands): Add /symlinks command"
/framework-sync --message "fix(scripts): Handle read-only permissions"
/framework-sync --message "docs(guides): Update contributor workflow"

References​

  • /framework-sync command: commands/framework-sync.md
  • /symlinks command: commands/symlinks.md
  • Initial setup: scripts/CODITECT-CORE-INITIAL-SETUP.py
  • Symlink manager: scripts/check-project-symlinks.py
  • Framework sync: scripts/framework-sync.py