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.
Before you start
Section titled “Before you start”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.
python .act/scripts/update.py --plan # show the diff and describe the later steps, write nothing but the update notepython .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
Section titled “Update channel”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 tagvX.Y.Zof the source. A project already past it, for example one that followedmain, hears “ahead of the newest release” and keeps its state.latestis the tip of the source’s default branch.--channel release|latestoverrides 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
releaseis the default or the value indocs/ai/config.md.--channel releaseand an invalid value stop with a hint to use--reforlatest. - On
releasethe session start reports “template release vX.Y.Z available”, onlatest“a template update is available”..act-lock.jsonrecords the installed tag astemplate.refonreleaseand the branch onlatest. - 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 showsupdate: 2.4.0onreleaseorupdate: <date>onlatest(the newer commit’s date asDD.MM.YYYYwhenlanguage-docsisde, elseYYYY-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 fromact-update.act-doctorreports a value other thanreleaseorlatest.
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.
Advisories
Section titled “Advisories”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.
The ten steps
Section titled “The ten steps”- Fetch the template into a temporary checkout. Nothing from it is run.
- Local changes. Checks whether you edited
.act/since the last update.--on-local-changes rescue|discard|abortanswers up front;rescuemoves your edits todocs/ai/local/first. - Diff from old to new, with rule and coding-rule IDs individually.
- Consent. Nothing is replaced before you agree. Before the prompt, each due migration is shown with its effect, one line each (
--planshows the same).--yesskips the prompt once you already agreed. - Replace
.act/as a whole. - Refresh the copies outside
.act/: unchanged skill copies and role bridges are replaced, copies you edited are kept and reported. Copies thatprofileorexclude(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 underdocs/ai/local/get their copies here too. New coding sets and groups are entered indocs/project/coding_rules.md(a new set unchecked, a new group of a checked set checked; see Own skills, roles and rules). Whiledocs/project/coding_rules.mdhas changes that are not committed, nothing is entered (the update commit would take them along):update.pysays 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.--planpreviews the sets and groups an update would enter. A changedmethodsrow indocs/ai/config.mdis applied here too (python .act/scripts/rules.py --sync-methodsdoes the same on its own). If you editeddocs/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 underdocs/ai/local/rules/that lacks the rule (it does not load). An unediteddocs/ai/rules.mdis 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.jsonrecords 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 withpython .act/scripts/rules.py --add-missing; the session start enters new rules the same way. Onlybuilderandreviewerkeep a-highvariant: generated variants of the other template roles are removed, each named in the preview and summary. The template’s roles (and their-highvariants) getomitClaudeMd: true, so workers no longer loadCLAUDE.md; your own roles and an explicitomitClaudeMd: falsestay as they are, and an own role without the field keeps loadingCLAUDE.md. Claude Code before 2.1.271 ignores the field, so workers there get the rules twice (costs tokens only). - Hooks and Git files. Reconciles the hook entries in
.claude/settings.jsonand the template blocks in.gitattributesand.gitignore, setsPYTHON_BASIC_REPL=1underenvthere (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": falsethere unlessartifacts: onis indocs/ai/config.md. An existing project therefore starts without theArtifacttool after the update. It also adds theStopentry of the checkmodel-switch(withSubagentStopit reports when a worker or the session continued on another model) and the 12SubagentStartentries 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 --workershows what a worker gets. It also keeps.act-local/out of IDE indexes: anexcludeFolderin every JetBrains.idea/*.iml, andfiles.watcherExcludein.vscode/settings.jsonwhere.vscode/exists. - 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, through007-changelog-file,CHANGELOG.mdin the project root. A file that exists is never touched, and one you delete does not come back.007-changelog-filenever overwrites or recreates aCHANGELOG.md; it creates none for a project that keeps its changelog under another name (changelog.md,CHANGES.md,HISTORY.md,NEWS.md) or haschangelog: release-notes-onlyoroffunder § Formats.008-done-entries-keepremoves the retireddone-entriesrow and its explanation fromdocs/ai/config.md(see Finished entries); the plan names what it would cut. - Bridges and doctor. First unedited generated bridges (
CLAUDE.md,AGENTS.md,docs/ai/rules.md) are refreshed; withsession-start-refreshatwarnoroffindocs/ai/config.md§ Checks they are only reported (“would refresh … not written”). Thendoctor.pychecks for drift; findings land indocs/ai/inbox/, never as a silent fix. Among them: an override underdocs/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 withpython .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. - Lock and commit.
.act-lock.jsonis rewritten and a commit is made, unless you pass--no-commit. A path that.gitignoreignores (for example with an allowlist such as*,!docs/) stays out of the commit, which names it. Uncommitted changes of yours todocs/ai/rules.md,.gitignoreand.gitattributesstay out of it too: the update still writes its addition there and names each such file so you can commit it yourself;--plannames 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.
When a question gets no input
Section titled “When a question gets no input”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/.
Tidying .act-local/
Section titled “Tidying .act-local/”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.
Upgrading to 2.6.0
Section titled “Upgrading to 2.6.0”From v2.5.0, run act-update as usual, then start a new session.
- Assignments that run tests need a
Tests:line besideWrite scope:; workers run tests only with it (see Roles). - Migration
008-done-entries-keepruns once: it removes thedone-entriesrow and its explanation paragraph fromdocs/ai/config.md. A project that haddelete(the default under Git) archives finished entries from now on; see Finished entries. cd-git(only withclaude-codeintools) refuses a Bash call that combinescdandgitand namesgit -C <folder>; to only be warned, add the rowcd-gitwithwarnunder § Checks (Checks).git branch -Dof a branch HEAD does not contain (for example one taken over by cherry-pick) is refused; merge it first, or setgit-discard: warn.CHANGELOG.md:act-updatecreates it andact-commitadds entries from then on; to avoid that, first add the rowchangelogwithoffunder § Formats ofdocs/ai/config.md(Formats);config.pycannot set a missing row,.act/skeleton/config.mdshows its shape.- Overrides of the core rules: if
docs/ai/local/overrides.act/rules/shared/00-core.md,10-safety.mdor20-code.md, copy in the new sentences ofR-role-worker,R-work-bounded-output,R-safe-approvalandR-code-encoding. outside-root-allow: an absolute entry outside the project and the home folder is read-only now, so writes there are refused. Afile: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.mdhas uncommitted changes (step 6). Commit, then runpython .act/scripts/rules.py --add-new-coding. - Findings of
act-doctorandrules.py:docs/ai/local/files whose template file is gone, and rule files shadowed by your own copy underdocs/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-configchanges only rows that exist. - Older than v2.2.0: such a project is no longer updated;
update.pystops and namesact-adopt(see Before you start). - Long
[Unreleased]entries:act-doctornames the entries of yourCHANGELOG.mdover 250 characters. Shorten them, or setchangelog-length: offindocs/ai/config.md§ Checks. - A source that is itself a set-up project: run
update.pyonce with--source <template address>, as its message names (see Before you start). - Copilot projects: compare the models in
.github/agents/with/modelafter the update, put differences into theCopilotcolumn ofdocs/ai/config.md§ Roles, then runpython .act/scripts/update.py --catch-up --yes. - Skill overrides: each one under
docs/ai/local/skills/is anact-doctorfinding until you keep it withpython .act/scripts/doctor.py --accept skill:<name>or delete it. .act-localas a link out of the project: a worker start with aWrite scope:orTests:line is refused now; make it a plain folder, or setworker-write-scopeandworker-scope-overlaptowarn.- Reasoning
noneindocs/ai/config.md§ Roles or a local role or skill file is read asdefaultnow;act-doctornames each place, writedefaultthere. The-highvariant of such a role runs athigh.
Upgrading to 2.5.0
Section titled “Upgrading to 2.5.0”From v2.4.0, run act-update as usual, then start a new session.
- Two migrations run once:
005-resources-fileaddsdocs/ai/local/resources.mdand006-docs-project-readmeaddsdocs/project/README.md; neither overwrites a file that is there or brings back one you deleted. An editeddocs/ai/rules.mdgets the new ruleR-docs-orderas 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 keysdone-entries,profile,exclude,docs-orderandown-rules-budgettake their default until you add the row under its section, copied from.act/skeleton/config.md;/act-configchanges only rows that exist.feedback: localis a new value of the existingfeedbackrow (/act-config feedback local). - Finished entries are deleted under Git (
done-entriesdefaults todeletethere; 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 --planlists it andpurge --alldeletes it, if you want that. To keep the old behaviour, adddone-entries: keepunder § Archive. - Without
profileandexcludeevery skill, role and rule file stays as before (full). docs-order:act-doctorchecks the order ofdocs/project/(§ Checks, defaultwarn, never blocking). Right after the update it names every file and folder the newdocs/project/README.mdhas no line for, and every folder of five or more entries without aREADME.mdof its own. Add the lines (.act/scripts/move_doc.pyand the step “Structure” ofact-audit-docshelp), or adddocs-order: off.- An existing
docs/ai/inbox/README.mdis not replaced; the ruleR-human-askcarries the new form of a question either way, and.act/skeleton/inbox/README.mdhas the new text if you want it. own-rules-budget:act-doctorwarns, never blocks, when the “Own rules” sections ofdocs/ai/rules.mdanddocs/project/coding_rules.mdtogether 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 theact-audit-docsscript atdocs/ai/local/skills/act-audit-docs/workflow.js, rename that file toworkflow.js.txt.- Optional: clickable entry ids are set up once per machine with
python .act/scripts/id_links_install.py, and again after eachact-update.
Upgrading to 2.4.0
Section titled “Upgrading to 2.4.0”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=1underenvin.claude/settings.json, removes the-highvariants of six roles (an assignment that named one names the role itself, orbuilder-high/reviewer-high), and in an editeddocs/ai/rules.mdmoves the lines ofR-safe-no-secret-diff,R-safe-git-resetandR-safe-git-discardto the block oforchestrator/30-cost.md, marks unchanged. - The session title follows the project’s name (
session-name, defaultproject).session-name: autoleaves naming to Claude Code; a title set with/renameorclaude -nis 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: offindocs/ai/config.mdswitches them off. act-local-tidyonly reports on its first run in a project (see above);act-local-keepprotects your own entries under.act-local/.act-version,act-export-settingsandact-load-settingsstart only when typed as a slash command.archive-shortenis no longer read and can go fromdocs/ai/config.md. Once every project on the machine is updated, an oldact-pycachefolder in the system temp directory can be deleted.
Upgrading to 2.3.0
Section titled “Upgrading to 2.3.0”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-updatebrings (see Update channel). A project withoutupdate-channelindocs/ai/config.mdfollowsreleaseand gets a one-time note; setupdate-channel: latestto keep following the default branch. - The check
outside-rootruns aswarnin a project without its row indocs/ai/config.md§ Checks. A one-time note at session start says how to switch it toblock; further allowed places go intooutside-root-allow. - Workers no longer load the orchestrator rules: the template’s roles get
omitClaudeMd: trueand.claude/settings.jsontheSubagentStartentries (step 7). Claude Code before 2.1.271 ignores the field, so workers there get the rules twice until Claude Code is updated.
Upgrading to 2.2.0
Section titled “Upgrading to 2.2.0”From v2.1.0, run act-update as usual; nothing else is needed. --plan first lists what will happen.
- Migrations
003and004move the header of every inbox entry (003) and of every task, backlog item, journal entry and archived entry underdocs/ai/work/(004) into YAML frontmatter between two---lines.docs/ai/work/archive/legacy/and everyREADME.mdstay as they are. Hand-written entries in the old form keep working. - Git 2.25 or newer is required for the update.
- The
Artifacttool is off after the update.artifacts: onindocs/ai/config.mdkeeps it. - Quick capture is on: a chat message that begins with
todo:,note:oridea:is filed by a hook without a model turn.quick-capture: offindocs/ai/config.mdswitches it off.
Finished entries
Section titled “Finished entries”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.
Downgrade guard
Section titled “Downgrade guard”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>.
Your own changes
Section titled “Your own changes”.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.
If .act/ was replaced another way
Section titled “If .act/ was replaced another way”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.