update-framework

name	update-framework
description	Bring an already framework-managed workspace into alignment with newer framework changes using minimal safe updates.

Skill: Update Framework

Purpose

Bring an already framework-managed workspace into alignment with newer framework changes using minimal safe updates.

When To Use

• when the framework repository in a workspace has been updated after time has passed
• when new framework features introduce additional setup or configuration steps
• when the workspace should be checked for drift against the current framework expectations

Recommended Roles

• Overseer
• Historian

Required Inputs

• framework/INSTALLATION.md
• framework/README.md
• framework/MIGRATIONS.md when present
• framework/WORKSPACE.md, framework/TASKS.md, and framework/SKILLS.md when present
• framework/VERSION
• framework/CURRENT_VERSION when present
• relevant templates under framework/TEMPLATES/
• the current workspace root contents
• local workspace/project skills and skill indexes when framework guidance changed
• the current framework files already present in the workspace

Steps

1. If the Operator asked to update from the remote framework repository, first check the framework/ working tree state, then pull the latest framework repo changes using the workspace's normal git flow. Do not pull over local framework edits or unresolved conflicts; ask before risky git operations.
2. Read framework/INSTALLATION.md to understand the current expected setup shape, including the phased adoption guidance for existing workspaces.
3. Read framework/CURRENT_VERSION if it exists, and read the newly pulled framework/VERSION.
4. If CURRENT_VERSION is missing, treat the workspace as having an unknown installed framework version, create it from VERSION after the update, and mention that version-specific diff review was not possible.
5. If both versions exist and differ, inspect the framework changes between the old installed version and the new VERSION before changing workspace files. Prefer git tag comparison when tags exist, for example git -C framework diff vOLD..vNEW -- INSTALLATION.md MIGRATIONS.md FRAMEWORK.md WORKSPACE.md TASKS.md SKILLS.md ROLES/ SKILLS/ TEMPLATES/ README.md USAGE-PROMPTS.md COMMANDS.md prompts/; otherwise compare the current files directly and note the limitation.
6. If framework/MIGRATIONS.md exists, read only the migration sections that apply between the old installed version and the new VERSION.
7. Inspect the workspace root for the existing framework-managed files and directories.
8. Compare the current workspace setup against the latest framework expectations.
9. Check the actual repository boundaries before editing config files so the update does not guess wrongly about which repo owns what.
10. Check whether the root .gitignore still matches the current framework repository model and ignore guidance.
11. Recheck that workspace-owned projects/[name]/library/ and projects/[name]/work/ are not being ignored under the default model.
12. When framework guidance changed, check local skill indexes and local skills for stale framework assumptions before declaring the workspace aligned:

• SKILLS/INDEX.md and SKILLS/*/SKILL.md;
• projects/[name]/SKILLS/INDEX.md and projects/[name]/SKILLS/*/SKILL.md;
• tool-native project skills or commands when they are relevant and supported by the current agent/tool.

13. Add newly required files or directories when they are missing and templates clearly apply.
14. If the newer framework includes optional tools such as framework/tools/tool-orchestrator/, framework/tools/session-browser/, or framework/tools/task-browser/, do not force workspace changes; tell the Operator the tools are available after updating framework/, and point them to the relevant tool READMEs for optional setup/use.
15. If the newer framework includes optional native command templates under framework/prompts/, do not force setup; tell the Operator they are available and point them to framework/COMMANDS.md for Pi symlink/copy setup and OpenCode guidance.
16. Update or merge existing workspace files only when needed to support new framework behavior or guidance.
17. Do not overwrite local workspace-specific instructions blindly.
18. If a merge is non-obvious, ask the user before changing the file.
19. Leave adapter-specific files such as CLAUDE.md intact unless the user explicitly wants them updated.
20. If the workspace uses other root agent/editor entrypoint files, decide deliberately whether they should mirror the same workspace guidance.
21. After the workspace has been updated, set framework/CURRENT_VERSION to match framework/VERSION.
22. Summarize the old version, new version, what changed, what was added, updated, left unchanged, or escalated.

Optional Framework Tool Check

If the updated framework includes optional browser tools:

1. Mention Framework Cockpit (framework/tools/tool-orchestrator/) to the Operator as an optional local shell for opening small framework browser tools from one place.
2. Mention Session Browser (framework/tools/session-browser/) as an optional local, read-only browser for Pi and OpenCode coding-agent sessions.
3. Mention Task Browser (framework/tools/task-browser/) as an optional local browser for tracked task directories and task-browser-owned metadata.
4. Do not force setup; the core framework workflow does not require these tools.
5. If the Operator wants to use Framework Cockpit, verify node --version and point to:
   • cd framework/tools/tool-orchestrator && npm start
   • open http://localhost:8789
6. If the Operator wants to use Session Browser directly, verify basic prerequisites:
   • node --version
   • optional for OpenCode: sqlite3 --version
7. Point to the Session Browser quick start:
   • cd framework/tools/session-browser && npm start
   • open http://localhost:8787
8. For workspace-specific setup, suggest only the env vars that matter:
   • WORKSPACE_ROOT=/path/to/workspace
   • SESSION_SOURCES=pi, SESSION_SOURCES=opencode, or SESSION_SOURCES=pi,opencode
   • PORT=8790 when the default port is busy
   • PI_SESSION_ROOT / SESSION_ROOT when Pi sessions are not in the default location
   • OPENCODE_DB / OPENCODE_DATA_DIR when OpenCode data is not in the default location
9. Remind the Operator that task metadata, session transcripts, cwd paths, tool outputs, copied databases, exports, logs, and env files can be sensitive.
10. Do not copy session files, OpenCode databases, exports, logs, local .env files, local .tools-config/, or legacy local .task-browser/ metadata into the framework repo.
11. For full details, refer to the relevant tool README under framework/tools/.

Outputs

• a workspace brought closer to the current framework expectations
• framework/CURRENT_VERSION updated to the installed framework version after successful sync
• only the necessary config/setup changes applied
• repo-boundary and root .gitignore expectations rechecked rather than assumed
• workspace-owned library/ and work preserved under the default repo model while nested project/ repositories remain ignored as expected
• a clear summary of required follow-up when user input was needed
• optional framework tools surfaced to the Operator without forcing workspace-specific setup

Stop Conditions

• the workspace no longer misses any newly required framework setup that clearly applies
• framework/CURRENT_VERSION matches framework/VERSION after successful sync
• any ambiguous merge or local-policy conflict has been escalated to the user

Pitfalls / Anti-Patterns

• treating update as a fresh install and recreating files unnecessarily
• assuming repo ownership from the folder layout without checking the real nested repositories
• accidentally gitignoring workspace-owned library/ or work paths while updating .gitignore
• overwriting customized AGENTS.md, .gitignore, README.md, or other workspace files blindly
• applying template changes that are not actually needed for the current framework update
• skipping applicable MIGRATIONS.md notes when framework behavior or file organization changed
• missing stale assumptions in workspace-custom or project-local skills after framework guidance changes
• copying private session data into framework/tools/session-browser/ or treating optional tools as required workspace setup
• updating CURRENT_VERSION before checking whether the old/new framework versions require workspace changes
• changing adapter-specific files by default

Related Files / Tools

• framework/INSTALLATION.md
• framework/README.md
• framework/MIGRATIONS.md
• framework/WORKSPACE.md
• framework/TASKS.md
• framework/SKILLS.md
• framework/TEMPLATES/WORKSPACE/
• framework/TEMPLATES/TASKS/