Upgrade¶

Migrate a v1.5.0 project to v2¶

v2 keeps AGENTS.md at the project root and moves Memory Bank files under tabilet/: GOAL.md, memory-bank/, evolution/, archives, and retired history. Other project documentation stays at the root. Installing v2 never moves these files, and v2 skills and the API runner stop on a legacy or mixed layout. The v2 DSH sidebar can display a v1.5.0 project read-only with a migration warning.

Use the standard-library command bundled with the Upgrade skill, or the same file in a v2 source checkout. Start from a committed, clean Git worktree:

python3 /path/to/skills/skills/memory-bank-upgrade/migrate-v1.5-to-v2.py /path/to/project
python3 /path/to/skills/skills/memory-bank-upgrade/migrate-v1.5-to-v2.py /path/to/project --apply

The first command only previews file actions. --apply moves the files, updates maintained instructions and indexes, preserves frozen archives and retired records byte-for-byte, and leaves the diff uncommitted for review. It reports path references in other project documents for manual review. It also supports all-retired projects, archive-only preflights, an absent or customized goal protocol, and local policies. For the unmodified v1.5.0 GOAL.md, it updates the one path example to the v2 location. A customized GOAL.md stays byte-for-byte intact and is always flagged for manual path review.

If interrupted, run the same command with --resume. It checks a temporary journal outside tracked project files, Git HEAD, and every planned file hash before continuing. An unexplained partial layout, symlink, or destination collision stops for manual repair. Once complete, a repeat run is a no-op.

After reviewing the diff and project checks, commit it under your project's normal policy. If workflow rules also need updating, use Upgrade below as a separate approved merge.

Upgrade workflow rules¶

Upgrade an existing memory bank's workflow rules through approved merges, preserving project plans, local policies, and history.

Send the request in a session for your project:

Agent	Conversation request
Claude Code plugin	`/memory-bank:memory-bank-upgrade`
Codex plugin	`$memory-bank:memory-bank-upgrade`
DSH	`/memory-bank-upgrade`

Argument: optionally, the workflow changes you want to adopt.

For direct skill-folder installs, see the invocation prefixes.

When to use it¶

After installing newer skills, when you want an existing project to adopt the new workflow rules.

The project must already have a milestone/status harness; an all-retired project with valid indexed history still qualifies. Pause other execution on the same ledger before applying the approved upgrade.

Installing newer skills cannot safely rewrite every project that used an older version. Those projects have their own commands, policies, plans, and history. An install never migrates a project. This skill is how adoption happens, and only with your approval.

Three phases¶

Inspect and compare. Upgrade compares the project's adopted workflow with the reference template bundled inside the skill. That bundle means no checkout and no network access is needed to inspect the target. It identifies missing rules, compatible local equivalents, deliberate exclusions, and conflicts that need a decision from you.

Propose and obtain approval. It presents specific file actions — focused section diffs rather than whole restated documents — and waits.

Apply and verify. After approval it applies the scoped merges and verifies that preservation actually held.

A useful request¶

Use memory-bank-upgrade to compare this project's workflow with the bundled
contract. Preserve our plans, local policies, task states, IDs, review counts,
and history. Show the complete proposed file changes before writing.

What is preserved¶

Task state, permanent identifiers, local policies, review counters, custom goal protocols, completed evidence, and frozen history. A project already compatible needs no changes at all.

Upgrade can adopt the optional stage rules without creating a stages document or moving current work. Use Propose when you want to introduce stages or withdraw already approved pending tasks for later planning.

Existing goal protocol and launch reference¶

The goal protocol ships with the skills and projects no longer keep a copy. When tabilet/GOAL.md exists, Upgrade classifies it against the bundled goal-protocol.json and includes the result in its complete proposal. First resolve explicit GOAL_PROTOCOL: preserve a file selected as the full alternative protocol instead of reducing or removing it as an addendum:

a byte-identical stock copy: Upgrade proposes removing it;
a full protocol copy with local edits: it shows the local differences and proposes reducing the file to those project-specific rules, and goal runs stop on it until you do;
anything else, such as a short addendum or a project record: kept as the project addendum.

Upgrade never writes a merged protocol. It also rewrites AGENTS.md and milestone.md pointers that name tabilet/GOAL.md as the protocol, and offers the template's Out of scope register as an explicit adoption.

Before removing or reducing the file, Upgrade inspects maintained incoming links throughout the project and includes their repairs in the proposal. Current execution pointers select the bundled protocol and optional addendum. Unfrozen historical references retain their recorded revision/path and are labelled as historical source references; they do not select today's protocol. Frozen records retain their bytes and original source-commit path context. If a required reference cannot be resolved, the file stays pending an approved solution. Removing a stock copy must not leave unexplained broken links.

When tabilet/memory-bank/suggested.txt also exists, Upgrade proposes a refresh against the whole live approved active horizon and adds the GOAL_IDENTITY block. It preserves explicit order or priority, commit, integration, external-mutation, and scope policies. It always includes AUTHORIZATION_GRANTS, using {} when no explicit grants are proposed, and labels nonempty proposals as unapproved. Existing grant text never transfers approval from a previous run. Requirements stay in milestone specifications, and stale historical IDs are reconciled before removal.

The complete file-action proposal must be approved before either update. Absent optional files remain absent by default; incompatible launch references need an explicit preserve/remove decision. An all-retired project gains no executable IDs. These updates never launch a goal or activate grants. Already compatible files yield a no-op.

What an upgrade is not¶

An upgrade adopts operating rules. It does not initialize a project, implement work, commit, or retire milestones as a side effect.

Retiring older milestones is separate work that needs its own scope and closure evidence. A separately installed API harness needs its own compatibility check or update.

Adopting authorization guidance¶

Offer optional milestone AUTHORIZATION_REQUIREMENTS and request AUTHORIZATION_GRANTS as an explicit approved merge. Preserve project restrictions and reconcile conflicts in the proposal. Keep declarations in milestone specifications; status preambles only point there. Upgrading guidance never activates proposed grants or authorizes execution.

Existing projects without these fields retain their behavior; installation triggers no migration or additional authority. Create no approval ledger or audit dependency, and leave frozen history untouched. Python API authorization boundaries stay governed by their existing contracts. See the authorization guide.

Adopting long-term memory¶

This is the skill that matters most for a project with months of history, because it is how lessons.md and milestone retirement arrive in a project that predates them.

Existing projects require explicit adoption. There is no automatic bulk migration, and retirement respects every commit policy.

If DSH reports compatibility warnings¶

You can prepare an Upgrade request even when the dashboard cannot read all the records. Insert into empty draft only prepares text; sending it asks the agent to inspect and propose changes. It does not approve a merge.

Include the warnings in the conversation: the sidebar displays them separately from the request text. Ask the agent to distinguish unsupported legacy syntax from actual ledger conflicts before proposing corrections. Preserve IDs, states, notes, review evidence, and history; do not bulk-rewrite them to clear a warning.

Preserving protocol and model selection¶

Refresh launch input for approved goal use with an available compatible governing protocol; the package-local tabilet/GOAL.md is optional. Preserve an explicit GOAL_PROTOCOL and its actual path/hash, invocation and package identities. Use bundled stock metadata only when stock is selected. A protocol switch requires explicit approval; unavailable selection pauses refresh and preserves existing input. Do not remove or truncate a file selected as an alternative full protocol through stock-addendum cleanup.

For legacy paused goals without GOAL_IDENTITY, show the old approved identity and proposed resolution. Changed or uncertain identity requires approval once, without resetting grants, denials, review counters, attempts or limits. Preserve an explicit MODEL_POLICY; propose it only when requested. Omission preserves host settings and an upgrade never activates model routing or resumes a goal.