AGENT NOTICE — CRITICAL PATH RULES

Rule 1: Canonical Memory Root

All memory-backed workflows in this repository resolve under this exact path:

${HOME}/Documents/Programming/agentic-workflow/memory

This is the only authoritative location for memory reads and writes.
Do not create alternate memory roots. Do not write memory data elsewhere.

Rule 2: Do Not Edit Mirrored / Linked Paths

This repository uses symlinks (or junctions on Windows) for daily use:

Source (edit here)	Mirrored to (do NOT edit here)
memory/	~/.config/opencode/memory
memory/	~/.codex/memory
configs/opencode/	~/.config/opencode/
skills/	~/.codex/skills/
skills/	~/.config/opencode/skills/ (when SYNC_OPENCODE=true)

Always edit files in this repository's working tree.
Changes made in mirrored/linked target locations will be overwritten or lost.

---

agentic-workflow

Requirements

• Python 3.8+ on all platforms (for scripts/sync_environment.py)
• just command runner (cross-platform)

Setup

Windows

1. Sync everything (recommended)

just sync-environment

This is the canonical command and syncs:

1. memory/ -> %USERPROFILE%\.config\opencode\memory and %USERPROFILE%\.codex\memory
2. configs/opencode/* -> %USERPROFILE%\.config\opencode/
3. skills/ -> %USERPROFILE%\.codex\skills/ (and optionally OpenCode)
4. configs/nvim/ -> %LOCALAPPDATA%\nvim

2. Sync only OpenCode config

just sync-opencode

This links configs\opencode\opencode.jsonc and configs\opencode\AGENTS.md into %USERPROFILE%\.config\opencode\.

If you want to open the config after linking, run:

just opencode-config

3. Sync only memory

just sync-memory

This symlinks memory\ into:

1. %USERPROFILE%\.config\opencode\memory
2. %USERPROFILE%\.codex\memory

4. Sync only skills

If you want OpenCode skill mirroring, copy .skills.env.example to .skills.env and set:

SYNC_OPENCODE=true

Then run:

just sync-skills

just sync-skills bootstraps skills\ into %USERPROFILE%\.codex\skills\. If SYNC_OPENCODE=true, it also mirrors into %USERPROFILE%\.config\opencode\skills.

5. Sync only Neovim config

just sync-nvim

This links %LOCALAPPDATA%\nvim to configs\nvim\ (repo is source of truth).

macOS / Linux

1. Sync everything (recommended)

just sync-environment

This is the canonical command and syncs memory, OpenCode config, skills, and Neovim.

2. Sync only OpenCode config

just sync-opencode

This symlinks configs/opencode/opencode.jsonc and configs/opencode/AGENTS.md into ~/.config/opencode/.

3. Sync only memory

just sync-memory

This symlinks memory/ into:

1. ~/.config/opencode/memory
2. ~/.codex/memory

4. Sync only skills

just sync-skills

This symlinks each skills/<name>/ folder into ~/.codex/skills/ (skipping folders with .codex-hidden).

To also mirror into OpenCode, copy .skills.env.example to .skills.env and set:

SYNC_OPENCODE=true

Then run just sync-skills again.

5. Sync only Neovim config

just sync-nvim

This links ~/.config/nvim to configs/nvim/ (repo is source of truth).

Daily use

1. Put each new skill in skills/<skill-name>/.
2. Run just sync-skills to sync new skill folders.
3. Run just sync-environment to sync everything at once.

Troubleshooting

1. If a sync command says a path already exists as a real file or directory, the script backs it up with a timestamp and creates the symlink.
2. On Windows, if symlink creation fails, the script falls back to junctions (directories) or hard links (files). Enable Windows Developer Mode for true symlinks.
3. On macOS/Linux, symlinks are created directly.
4. If python is not on your PATH, install Python 3.8+ or use your package manager.
5. On Linux, Homebrew may install python3 without a python symlink. Fix with:

   ln -s /home/linuxbrew/.linuxbrew/bin/python3 /home/linuxbrew/.linuxbrew/bin/python