| 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.
