Skip to content

Update

act-update brings a newer template state into your project: you see the diff, you consent, and python .act/scripts/update.py does the rest. There is no merge and nothing to resolve by hand. Say Check for a template update or run the script yourself.

Commit or finish open work first (git status should be clean). Updating needs Git 2.25 or newer. The template’s address lives in .act-lock.json (template.source); --source and --ref pick another source or a tag. The source recorded there comes first: a git remote named template is used only if the lock names no source, and the script says which one it took. If the fetch fails, the message names the source, where it came from, and the way out (--source, --ref). A source that is itself a set-up project is refused; update.py names --source <template address>, so run it once with that. A project on a template version older than v2.2.0 is no longer updated: update.py stops before it changes anything and names act-adopt (run from a current template checkout or project, with this folder as <dir>), which carries the project’s docs and own rules over.

Terminal window
python .act/scripts/update.py --plan # show the diff and describe the later steps, write nothing but the update note
python .act/scripts/update.py # the real run, asks for consent

--plan names the fetched commit and keeps it for an hour. A real run within that hour (same source and channel, no --ref) applies exactly that commit and says so when the source has moved on since; a rewritten source is refused. A source that is a plain folder has no commit, so it gets no plan file.

update-channel in docs/ai/config.md § Update decides what act-update offers. init asks for it and writes it.

  • release (the default) is the newest stable tag vX.Y.Z of the source. A project already past it, for example one that followed main, hears “ahead of the newest release” and keeps its state.
  • latest is the tip of the source’s default branch.
  • --channel release|latest overrides the key for one run; --ref <tag-or-commit> beats both.
  • A source without release tags is followed at its tip, with a note, while release is the default or the value in docs/ai/config.md. --channel release and an invalid value stop with a hint to use --ref or latest.
  • On release the session start reports “template release vX.Y.Z available”, on latest “a template update is available”. .act-lock.json records the installed tag as template.ref on release and the branch on latest.
  • A pending update stays visible until it is installed: the session start names it in the line you see (update 2.4.0 available) and repeats it to the assistant at every start, the board lists it under Status, and Claude Code’s status line shows update: 2.4.0 on release or update: <date> on latest (the newer commit’s date as DD.MM.YYYY when language-docs is de, else YYYY-MM-DD; its short hash where the date cannot be read without the network). If the lock has moved on since the check (an update pulled from another checkout), the old finding is dropped and the next check runs at once.
  • Existing projects keep their config.md; without the key they get a one-time note from act-update. act-doctor reports a value other than release or latest.

To see where you stand, ask /act-version: a hook answers it before the model sees it, in three lines (the installed version and when it came in, the newest state of the source in your channel with its date, and whether an update is available). /act-version --all gives the long list, which is also what python .act/scripts/update.py --versions prints (--versions --short is the three-line form): the installed version and channel, the source’s releases (--all for every one, not the five newest), the tip of the default branch, and what act-update would take. The long list uses only git ls-remote; the three-line form may also fetch the single commit object to read its date (no trees, nothing checked out); neither clones. The only thing it writes is the local update note under .act-local/ (status line, board), judged for the project’s own channel and source. --plan and an update run refresh that note too (or clear it when the project is up to date); --channel, --source and --ref aim a single run elsewhere and leave it alone. act-update answers a question about the installed or newest version with update.py --versions --short.

The template author can warn projects that run an affected template version. The daily background update check also looks at the advisories branch of the template source and, when it changed, fetches only that branch into .act-local/advisories.git (never the project’s .git). Only validated JSON is used; a link is shown, never opened. A critical advisory that matches the installed version shows at every session start, as ⚠ A<n> in the status line, below the board title and once as an inbox todo; a warning shows at session start only, once or at every start as the advisory sets it.

An advisory ends when act-update brings a version outside its range, when you say “warning acknowledged” (or run python .act/scripts/advisory.py --ack A<n>), or when the files it lists no longer hold the faulty snippet. A critical advisory whose inbox todo was done and deleted (an older template version deleted finished entries) is not filed again on another workstation: advisory.py also searches the git history, read only and time-bounded (the newest 2000 commits that touched the inbox or the archive, at most 3 candidate files, about 4 seconds), for a deleted todo with the same heading. advisory-check: off in docs/ai/config.md switches it off; advisory.py --status shows the state and --refresh checks at once. The check’s git ls-remote allows only the file, git, http, https and ssh protocols: a source behind another remote helper gets no update note at session start, while act-update itself is unchanged.

  1. Fetch the template into a temporary checkout. Nothing from it is run.
  2. Local changes. Checks whether you edited .act/ since the last update. --on-local-changes rescue|discard|abort answers up front; rescue moves your edits to docs/ai/local/ first.
  3. Diff from old to new, with rule and coding-rule IDs individually.
  4. Consent. Nothing is replaced before you agree. Before the prompt, each due migration is shown with its effect, one line each (--plan shows the same). --yes skips the prompt once you already agreed.
  5. Replace .act/ as a whole.
  6. Refresh the copies outside .act/: unchanged skill copies and role bridges are replaced, copies you edited are kept and reported. Copies that profile or exclude (Scope) leave out are not written; an unedited copy already there is removed, an edited one is kept, and both are reported. Own skills and roles under docs/ai/local/ get their copies here too. New coding sets and groups are entered in docs/project/coding_rules.md (a new set unchecked, a new group of a checked set checked; see Own skills, roles and rules). While docs/project/coding_rules.md has changes that are not committed, nothing is entered (the update commit would take them along): update.py says so in this step and in the closing notes and names the command to run after committing, python .act/scripts/rules.py --add-new-coding. --plan previews the sets and groups an update would enter. A changed methods row in docs/ai/config.md is applied here too (python .act/scripts/rules.py --sync-methods does the same on its own). If you edited docs/ai/rules.md, a rule that moved to another rule file takes its checkbox line along (mark and reason unchanged, so a rule switched off stays off); if you do not import the new file, it is only reported, and so is a rule that moved into a file your project shadows with its own copy under docs/ai/local/rules/ that lacks the rule (it does not load). An unedited docs/ai/rules.md is re-derived as before. In an edited one, a rule or rule file the template added is entered: a checkbox line per new rule, a new rule file as an import block at the end of its section. Your own text, unchecked boxes and imports you removed stay as they are, and .act-lock.json records what was offered (rules_offered), so a removed line does not come back, and its rule still counts as on (remove the cross to switch it off). What cannot be entered safely is named with python .act/scripts/rules.py --add-missing; the session start enters new rules the same way. Only builder and reviewer keep a -high variant: generated variants of the other template roles are removed, each named in the preview and summary. The template’s roles (and their -high variants) get omitClaudeMd: true, so workers no longer load CLAUDE.md; your own roles and an explicit omitClaudeMd: false stay as they are, and an own role without the field keeps loading CLAUDE.md. Claude Code before 2.1.271 ignores the field, so workers there get the rules twice (costs tokens only).
  7. Hooks and Git files. Reconciles the hook entries in .claude/settings.json and the template blocks in .gitattributes and .gitignore, sets PYTHON_BASIC_REPL=1 under env there (on Windows, an empty heredoc in a Bash call no longer hangs on Python 3.13 and later; a value you set yourself is kept, and the report names the env keys added), and sets "enableArtifact": false there unless artifacts: on is in docs/ai/config.md. An existing project therefore starts without the Artifact tool after the update. It also adds the Stop entry of the check model-switch (with SubagentStop it reports when a worker or the session continued on another model) and the 12 SubagentStart entries that give workers their rules without the orchestrator rules (see step 6); an older set of six is replaced, your own hooks stay. python .act/scripts/rules.py --worker shows what a worker gets. It also keeps .act-local/ out of IDE indexes: an excludeFolder in every JetBrains .idea/*.iml, and files.watcherExclude in .vscode/settings.json where .vscode/ exists.
  8. Migrations. Runs any that are due. Each rewrites an affected file once and leaves it alone after. Three give an existing project a missing file once: docs/ai/local/resources.md (your reading list), docs/project/README.md (the index of the project docs) and, through 007-changelog-file, CHANGELOG.md in the project root. A file that exists is never touched, and one you delete does not come back. 007-changelog-file never overwrites or recreates a CHANGELOG.md; it creates none for a project that keeps its changelog under another name (changelog.md, CHANGES.md, HISTORY.md, NEWS.md) or has changelog: release-notes-only or off under § Formats. 008-done-entries-keep removes the retired done-entries row and its explanation from docs/ai/config.md (see Finished entries); the plan names what it would cut.
  9. Bridges and doctor. First unedited generated bridges (CLAUDE.md, AGENTS.md, docs/ai/rules.md) are refreshed; with session-start-refresh at warn or off in docs/ai/config.md § Checks they are only reported (“would refresh … not written”). Then doctor.py checks for drift; findings land in docs/ai/inbox/, never as a silent fix. Among them: an override under docs/ai/local/ whose counterpart under .act/ is gone (the template renamed or removed it, so the override has no effect), with the most similar name under .act/; rule overrides, roles and your own skills are left out, and so is an own script or coding set unless one name is the start of the other or differs only in its extension. A local skill that overrides a template skill of the same name is a finding too, until you keep it with python .act/scripts/doctor.py --accept skill:<name> or delete it (own-rules-review). A new tier proposal is filed there as a question of its own, and only once a role has 30 recorded outcomes at a tier and at least 60 % of the last 30 were reworked or escalated. The question is short and recommends option a), looking at the cases first; its numbers are in a separate inbox report, report-<date>-<time>-tier-numbers-<role>-<tier>.md. The commit takes the report and the questions, and the summary names both.
  10. Lock and commit. .act-lock.json is rewritten and a commit is made, unless you pass --no-commit. A path that .gitignore ignores (for example with an allowlist such as *, !docs/) stays out of the commit, which names it. Uncommitted changes of yours to docs/ai/rules.md, .gitignore and .gitattributes stay out of it too: the update still writes its addition there and names each such file so you can commit it yourself; --plan names the ones it would write.

The summary also says how much the next session start will remove from .act-local/ (the check act-local-tidy, see below).

In a Copilot project (copilot in tools), compare the models in .github/agents/ with /model after the update and put differences into the Copilot column of docs/ai/config.md § Roles, then run python .act/scripts/update.py --catch-up --yes.

Unless own-rules-review is off, act-update then sets the new and changed rules and skills of the update against your own rules, overrides and skills and, where it finds overlaps, asks one inbox question: drop, keep or adapt; nothing is deleted.

Then comes the package step. With packages-update: ask (the default, Packages) act-update fetches each active package (python .act/scripts/packages.py fetch <id>) and, for each one whose fetched version is newer, runs /act-packages update <id> (skill act-packages): its plan and diff, your yes to that plan, only then the change. One yes per package, never one for all; a source that cannot deliver is named and skipped. packages-update: off, or no active package, skips the step. update.py itself only names a package whose requires-template the new template no longer meets or whose newer zip is already there.

If .act-local is a link out of the project, a worker start with a Write scope: or Tests: line is now refused: make it a plain folder, or set worker-write-scope and worker-scope-overlap to warn.

If the template has no newer state, --plan and the real run both say “nothing to update”. A bridge file whose content would not change is not rewritten. A large update no longer fails on Windows with WinError 206.

If update.py asks a question and no input arrives although stdin looks like a terminal (on Windows < /dev/null counts as one), it takes the safe default instead of stopping with a traceback: no consent to the update, and abort on local changes in .act/.

The session-start check act-local-tidy runs once a day in the background. It removes tmp/ entries and unknown entries directly under .act-local/ older than 7 days (unless the name starts with an open task’s id or act-local-keep in docs/ai/config.md § Checks lists it; throwaway material lives in tmp/<task-id>-<slug>/, or tmp/<YYYYMMDD>-<slug>/ for work with no task), all but the newest 5 backups of update, and compiled-module files (.pyc) under .act-local/pyc/ that belong to another Python version than the running one and are older than 7 days (links are not followed, files of the running version are never touched). The first run only reports what it would remove; removal starts the day after a session start has shown that report. act-local-tidy: warn only reports, off skips it. python .act/scripts/act_local_tidy.py lists what would go.

Then the assistant adds a journal line with the base-commit change and the number of findings.

From v2.5.0, run act-update as usual, then start a new session.

  • Assignments that run tests need a Tests: line beside Write scope:; workers run tests only with it (see Roles).
  • Migration 008-done-entries-keep runs once: it removes the done-entries row and its explanation paragraph from docs/ai/config.md. A project that had delete (the default under Git) archives finished entries from now on; see Finished entries.
  • cd-git (only with claude-code in tools) refuses a Bash call that combines cd and git and names git -C <folder>; to only be warned, add the row cd-git with warn under § Checks (Checks).
  • git branch -D of a branch HEAD does not contain (for example one taken over by cherry-pick) is refused; merge it first, or set git-discard: warn.
  • CHANGELOG.md: act-update creates it and act-commit adds entries from then on; to avoid that, first add the row changelog with off under § Formats of docs/ai/config.md (Formats); config.py cannot set a missing row, .act/skeleton/config.md shows its shape.
  • Overrides of the core rules: if docs/ai/local/ overrides .act/rules/shared/00-core.md, 10-safety.md or 20-code.md, copy in the new sentences of R-role-worker, R-work-bounded-output, R-safe-approval and R-code-encoding.
  • outside-root-allow: an absolute entry outside the project and the home folder is read-only now, so writes there are refused. A file: entry is ignored; write the path instead.
  • Lock files: a commit that touches a lock file is held while the scan cache folder is a link or junction; the message names it. Make it a real folder, or set security-check: off.
  • New coding rule sets are skipped while docs/project/coding_rules.md has uncommitted changes (step 6). Commit, then run python .act/scripts/rules.py --add-new-coding.
  • Findings of act-doctor and rules.py: docs/ai/local/ files whose template file is gone, and rule files shadowed by your own copy under docs/ai/local/rules/. Fix what is named.
  • New keys (§ Formats, methods, cd-git, protected-watch …) take their default until you copy their row from .act/skeleton/config.md; /act-config changes only rows that exist.
  • Older than v2.2.0: such a project is no longer updated; update.py stops and names act-adopt (see Before you start).
  • Long [Unreleased] entries: act-doctor names the entries of your CHANGELOG.md over 250 characters. Shorten them, or set changelog-length: off in docs/ai/config.md § Checks.
  • A source that is itself a set-up project: run update.py once with --source <template address>, as its message names (see Before you start).
  • Copilot projects: compare the models in .github/agents/ with /model after the update, put differences into the Copilot column of docs/ai/config.md § Roles, then run python .act/scripts/update.py --catch-up --yes.
  • Skill overrides: each one under docs/ai/local/skills/ is an act-doctor finding until you keep it with python .act/scripts/doctor.py --accept skill:<name> or delete it.
  • .act-local as a link out of the project: a worker start with a Write scope: or Tests: line is refused now; make it a plain folder, or set worker-write-scope and worker-scope-overlap to warn.
  • Reasoning none in docs/ai/config.md § Roles or a local role or skill file is read as default now; act-doctor names each place, write default there. The -high variant of such a role runs at high.

From v2.4.0, run act-update as usual, then start a new session.

  • Two migrations run once: 005-resources-file adds docs/ai/local/resources.md and 006-docs-project-readme adds docs/project/README.md; neither overwrites a file that is there or brings back one you deleted. An edited docs/ai/rules.md gets the new rule R-docs-order as a checkbox line; your own text stays.
  • Config rows are not added. The update adds no rows to an existing docs/ai/config.md. The new keys done-entries, profile, exclude, docs-order and own-rules-budget take their default until you add the row under its section, copied from .act/skeleton/config.md; /act-config changes only rows that exist. feedback: local is a new value of the existing feedback row (/act-config feedback local).
  • Finished entries are deleted under Git (done-entries defaults to delete there; see Finished entries). The archive you already have stays, and the first session start names its file count; python .act/scripts/entries.py purge --all --plan lists it and purge --all deletes it, if you want that. To keep the old behaviour, add done-entries: keep under § Archive.
  • Without profile and exclude every skill, role and rule file stays as before (full).
  • docs-order: act-doctor checks the order of docs/project/ (§ Checks, default warn, never blocking). Right after the update it names every file and folder the new docs/project/README.md has no line for, and every folder of five or more entries without a README.md of its own. Add the lines (.act/scripts/move_doc.py and the step “Structure” of act-audit-docs help), or add docs-order: off.
  • An existing docs/ai/inbox/README.md is not replaced; the rule R-human-ask carries the new form of a question either way, and .act/skeleton/inbox/README.md has the new text if you want it.
  • own-rules-budget: act-doctor warns, never blocks, when the “Own rules” sections of docs/ai/rules.md and docs/project/coding_rules.md together exceed 6000 characters; set the key in § Checks to raise the limit or switch it off. It also checks every setting that has a fixed list or format and may report a value it passed over before. A value that ends in a backslash right before the next | needs a space before the |.
  • workflow.js.txt: if the project overrides the act-audit-docs script at docs/ai/local/skills/act-audit-docs/workflow.js, rename that file to workflow.js.txt.
  • Optional: clickable entry ids are set up once per machine with python .act/scripts/id_links_install.py, and again after each act-update.

From v2.3.0, run act-update as usual, then start a new session so the new hooks take effect. There is no new migration.

  • Settings, roles and rule lines (steps 6 and 7): the update sets PYTHON_BASIC_REPL=1 under env in .claude/settings.json, removes the -high variants of six roles (an assignment that named one names the role itself, or builder-high/reviewer-high), and in an edited docs/ai/rules.md moves the lines of R-safe-no-secret-diff, R-safe-git-reset and R-safe-git-discard to the block of orchestrator/30-cost.md, marks unchanged.
  • The session title follows the project’s name (session-name, default project). session-name: auto leaves naming to Claude Code; a title set with /rename or claude -n is never overwritten.
  • Workers with a Write scope: line can no longer write to the system temp directory or their scratchpad. An assignment that needs throwaway material names .act-local/tmp/<task-id>-<slug>/** in its scope.
  • Advisories are on (see Advisories); advisory-check: off in docs/ai/config.md switches them off.
  • act-local-tidy only reports on its first run in a project (see above); act-local-keep protects your own entries under .act-local/.
  • act-version, act-export-settings and act-load-settings start only when typed as a slash command.
  • archive-shorten is no longer read and can go from docs/ai/config.md. Once every project on the machine is updated, an old act-pycache folder in the system temp directory can be deleted.

From v2.2.0, run act-update as usual, then start a new session so the new hooks and role fields take effect. There is no new migration.

  • The update channel decides what the next act-update brings (see Update channel). A project without update-channel in docs/ai/config.md follows release and gets a one-time note; set update-channel: latest to keep following the default branch.
  • The check outside-root runs as warn in a project without its row in docs/ai/config.md § Checks. A one-time note at session start says how to switch it to block; further allowed places go into outside-root-allow.
  • Workers no longer load the orchestrator rules: the template’s roles get omitClaudeMd: true and .claude/settings.json the SubagentStart entries (step 7). Claude Code before 2.1.271 ignores the field, so workers there get the rules twice until Claude Code is updated.

From v2.1.0, run act-update as usual; nothing else is needed. --plan first lists what will happen.

  • Migrations 003 and 004 move the header of every inbox entry (003) and of every task, backlog item, journal entry and archived entry under docs/ai/work/ (004) into YAML frontmatter between two --- lines. docs/ai/work/archive/legacy/ and every README.md stay as they are. Hand-written entries in the old form keep working.
  • Git 2.25 or newer is required for the update.
  • The Artifact tool is off after the update. artifacts: on in docs/ai/config.md keeps it.
  • Quick capture is on: a chat message that begins with todo:, note: or idea: is filed by a hook without a model turn. quick-capture: off in docs/ai/config.md switches it off.

The config key done-entries is retired. A finished task, backlog item or inbox entry is always moved to docs/ai/work/archive/ by entries.py archive, which is what done-entries: keep did; nothing is deleted there, and the same goes for a concept file that is decided or built (entries.py archive <path>). Nothing leaves docs/ before it stands in its monthly file: act-compact later folds the single files into Q-, T-, B-, U-<YYYY-MM>.md (concepts into other-<YYYY-MM>.md) with an overview <YYYY-MM>.md, and Git still holds the full text (see Archive).

A project that had delete (the default under Git) archives from now on; migration 008-done-entries-keep removes the done-entries row, and a row left behind is ignored. What an older version deleted stays in Git history and is not rebuilt. entries.py purge only prints a notice (purge is retired) and exits 0, so an old call does not fail; the options --plan and --all are ignored, and a leftover purge: after-commit in an archived file is left as it is.

If the fetched state is older than the installed one, or the installed commit is unknown to the source (for example a local checkout with unpushed commits), --plan warns and a real run refuses unless you pass --allow-downgrade. The usual fix is --source <local template checkout>.

.act/ is replaced, so never edit it. Put a project version of a rule, skill, or role into docs/ai/local/<same path>; if you override the act-audit-docs script workflow.js, rename your file to workflow.js.txt (the template’s script has that name now, and the update removes the old one). An update never overwrites that folder or your own content in docs/ai/ and docs/project/. It refreshes only unedited generated files (such as an unedited docs/ai/rules.md; an existing docs/ai/inbox/README.md is not replaced, the rule R-human-ask carries the form of a question), files findings in the inbox and runs migrations. See Layers and overrides.

After a plain git pull of the template or a manual copy, a normal run notices it and resumes instead of reporting “nothing to update”. --catch-up finishes the later steps from the .act/ on disk without a fetch; it refuses if .act/ no longer matches its own MANIFEST.json.