New project
Get the template
Section titled “Get the template”Clone the template repository, or use Use this template on GitHub, then open the folder in your assistant: Claude Code, Codex, GitHub Copilot, Cursor, or Gemini CLI. You need Python 3.9 or newer and Git 2.25 or newer; the assistant checks for Python and explains the installation if it is missing.
With the assistant: act-setup
Section titled “With the assistant: act-setup”Whatever your first message is, the assistant starts the act-setup skill. It checks for Python, asks where
the project goes, shows the plan, and runs it. For example:
startSet up a new project right here.Set up a new project in ../shop-api.Take over my existing project in ~/dev/shop — it already has a CLAUDE.md and its own docs.Any language works. With copilot in tools, act-setup also shows a short table of role and model, read from
.github/agents/; compare it with /model in Copilot, put a difference into the Copilot column of
docs/ai/config.md § Roles (add the column to the table head if it is missing), then run
python .act/scripts/update.py --catch-up --yes. There are three ways:
- Right here. The clone becomes the project. The
originremote is removed if it points at the template repository, and the project starts on a freshmainwith no history of the template. Later template updates come only throughact-update. - Somewhere else. An empty or missing folder is set up directly with
--target. The folder must lie outside the project you run it from (not the project itself, not a folder inside it, also not through a symlink or junction);init.pyrefuses that and creates nothing. - An existing project. A folder that already holds a project — its own docs, a
CLAUDE.md, an older AI setup — is taken over withact-adopt. The assistant sights every documentation and AI-tool source, proposes an action per source, waits until you approve the table once, then moves the material over on a branchact-adoptwithout committing it. The steps are on Existing project.
Once a project runs the template, /act-adopt there starts the next project or adopts another one from it, and can
carry its own skills, rules, exceptions, overrides, topics and agents over (--carry); see
Existing project. Afterwards the assistant
suggests act-update in the new project, since it got the .act/ of the project it came from. Its template source comes from the lock of that project only if
it is a remote address; otherwise the published template address is used.
Before it runs, the assistant asks once whether a working method should be on (test-first, spec-first,
simple-changes; none is the default) and passes the answer as --methods. The methods row in docs/ai/config.md
§ Scope changes it any time.
The assistant runs the commands itself. It has no terminal to ask you questions in, so init.py takes its
defaults and writes every open point (name, owner, stack, tools) to the inbox. You go through that note with
the assistant and the answers go into docs/ai/config.md. Without an answer, feedback defaults to confirm: every
message to the template author is shown and sent only after your yes. off is one edit away in docs/ai/config.md, and so is local: nothing is ever sent, and findings become backlog entries in the project. /act-config feedback local sets it without a model turn; /act-config alone lists every setting.
By hand: init.py
Section titled “By hand: init.py”The setup needs no AI. In a terminal, init.py asks for name, owner, stack, lint and test commands, tools, and
languages:
python .act/scripts/init.py --plan # show what would happen, change nothingpython .act/scripts/init.py # turn this clone into the projectpython .act/scripts/init.py --target ../my-project # set up a new, empty folder insteadpython .act/scripts/init.py --non-interactive # no questions: defaults, open points to the inboxUseful options: --language-docs <code> (language of docs/, default en), --language-chat <code|auto>,
--update-channel <release|latest> (what act-update follows, see Update; init asks if you leave it out), --methods <names|none> (working methods to switch on; init asks if you leave it out), --carry <list> (with --target, run from a project: what to take over from it: skills, rules, exceptions, overrides, topics, agents; default all), --no-commit. All options are in the scripts reference.
For an existing project, init.py --target <dir> never overwrites a file. It adds .act/ and whatever is
missing, appends its own blocks to .gitignore/.gitattributes, merges its hook entries into
.claude/settings.json, and leaves every other file exactly as it is — including an existing CLAUDE.md, which then
still lacks the import of the rules. What should become of the project’s own docs and AI files is a judgment per
file, and that takes an assistant: act-adopt.
What init does
Section titled “What init does”Ten fixed steps, each printed as [n/10]:
- Collects the settings: name, owner, languages, stack, commands, tools, mode, feedback, update channel (
releaseorlatest, written todocs/ai/config.md§ Update), working methods (methods, defaultnone) and the scope profile (profilein § Scope:fullfor a web project, elsestandard, decided from the stack;--scopesets it). It notes when the clone is already past the newest release. - Resolves Git: in place it removes
originand rebuildsmain; with--targetit runsgit initif needed. - Checks your Git identity.
- Writes your workspace identity (also when
.act-local/identity.jsonexists but lacksidentity) and the local import folder.act-local/import/. - Thins the bridges down to the tools you chose.
- Writes the skeleton:
docs/ai/(config.md,rules.md,concept/, inbox, work folders),docs/project/coding_rules.md,docs/project/glossary.md,docs/project/README.md(the index of the project docs, one line per file),docs/ai/local/resources.md,docs/README.md, the bridge files, skill copies and the hook entries in.claude/settings.json(with"enableArtifact": falseunlessartifacts: on, andPYTHON_BASIC_REPL=1underenv, so that on Windows an empty heredoc in a Bash call cannot hang on Python 3.13 and later). Skill copies and role bridges thatprofileorexcludeindocs/ai/config.md§ Scope leave out are not written. - Appends template blocks to
.gitattributesand.gitignore, and keeps.act-local/out of IDE indexes (excludeFolderin.idea/*.iml,files.watcherExcludein.vscode/settings.jsonwhere.vscode/exists). - In place only: retires the template’s own README (the new one follows the
readme-formatlayout of Formats,standardby default),CHANGELOG.md, and community files under.github/(contributing, security, code of conduct, accessibility, issue and pull request templates), and asks whether to keep its LICENSE. In place and with--targetalike it then creates the project’s ownCHANGELOG.mdwith an empty## [Unreleased]section, unlesschangelogin § Formats isrelease-notes-onlyoroffor the project already keeps a changelog under another name; an existing file is never overwritten. - Writes
.act-lock.json(the recorded template source and version) and.act/MANIFEST.json. - Makes the first commit. It takes only the paths this run wrote; anything else already staged in the target stays staged and is named in the output. A path the target’s
.gitignoreignores (an allowlist such as*,!docs/) stays out of the commit, which names it; an ignoredCHANGELOG.mdis not created.
init.py never overwrites a file the project already has. A question that gets no input takes its shown default. A language-docs other than English leaves the
scaffold in English. act-setup translates it in the same run; after a plain init.py an inbox note asks the
assistant to do it once;
common English technical terms (Skill, Inbox, Hook, Branch …) stay, above all in headings.
Your first session
Section titled “Your first session”Open the project in your assistant and say continue. The assistant reads the board and the inbox. Start with
the init notes in docs/ai/inbox/, then try an idea (Idea: export the orders as CSV), a bug (Bug: login fails with an umlaut), or Which skills are there?. Settings live in docs/ai/config.md.