update-agentflow-harness

name	update-agentflow-harness
description	Compare a client AgentFlow harness with the latest published release and safely apply compatible updates when the user explicitly requests it.

Update AgentFlow Harness

Use this global skill only when the user explicitly asks to compare, update, or refresh AgentFlow in the current client project. Do not apply source changes to client repositories while working on the AgentFlow source repository.

Run the bundled updater from this skill directory:

python3 <update-agentflow-harness-skill>/scripts/update_harness.py --project . --check

Read the JSON report. It identifies the installed harness version, the latest published version, installed client profile, detected repository stack, published changes, safe file updates, and any local conflicts. Draft releases are not offered to clients and must not be copied from the AgentFlow source tree.

Keep an existing harnessProfile by default. For legacy clients without one, the updater inspects repository files and adopts a supported profile only when the published release contains it. Never switch an already-profiled client merely because detection changes. When the user explicitly asks to change profiles, inspect the repository and pass the selected profile to both check and apply:

python3 <update-agentflow-harness-skill>/scripts/update_harness.py \
  --project . --profile django --check
python3 <update-agentflow-harness-skill>/scripts/update_harness.py \
  --project . --profile django --apply

When an update is available with no conflicts, apply it and verify the client is current:

python3 <update-agentflow-harness-skill>/scripts/update_harness.py --project . --apply
python3 <update-agentflow-harness-skill>/scripts/update_harness.py --project . --check

After managed files update, inspect whether the installed lifecycle requires an architecture-state migration or offers a safe correction from preserved v3 state:

python3 .agentflow/scripts/agentflow.py migrate --check

When required is true, the user's explicit harness-update request also authorizes this compatible migration. Read the reported source schema, target schema, installed profile, legacy revision, and converted page count, then run:

python3 .agentflow/scripts/agentflow.py migrate --apply
python3 .agentflow/scripts/agentflow.py validate
python3 .agentflow/scripts/agentflow.py status
make agentflow

The migration preserves legacy history under .agentflow/legacy-v3/. Do not edit converted immutable revisions directly. Do not open .agentflow/index.html automatically.

For a client that is already v4 but whose status reports a preserved legacy archive, inspect whether the installed profile requires a correction. A Django client that was migrated before profile-aware navigation needs this official lifecycle instead of a normal proposal:

python3 .agentflow/scripts/agentflow.py migrate --rebuild-from-v3 --check
python3 .agentflow/scripts/agentflow.py migrate --rebuild-from-v3 --apply
python3 .agentflow/scripts/agentflow.py validate
python3 .agentflow/scripts/agentflow.py status
make agentflow

The rebuild writes a new immutable generated revision from .agentflow/legacy-v3/ while retaining the original v3 and previous v4 migration history. If it reports MIGRATION_REBUILD_UNSAFE or MIGRATION_OWNERSHIP_UNRESOLVED, do not edit immutable revisions or architecture JSON by hand. Report the listed client work or unresolved artifact ownership and wait for the user to choose how to proceed.

The updater reads files from the immutable bundle belonging to the latest published release. It changes only files recorded as AgentFlow-managed in .agentflow/harness.json and the marked AgentFlow section of AGENTS.md. It preserves architecture revisions, proposals, comments, plans, memories, client-specific rules and skills, and the rest of shared files such as AGENTS.md and Makefile.

If the report contains conflicts, says the client is unversioned, or identifies an unpublished client version, do not rerun bootstrap and do not overwrite files by hand. Explain the affected paths, inspect them when useful, and ask before performing a targeted migration. After a successful update and any required architecture migration, review the changed files and commit them with the client project's intended work.