Skip to content

New project

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.

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:

start
Set 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:

  1. Right here. The clone becomes the project. The origin remote is removed if it points at the template repository, and the project starts on a fresh main with no history of the template. Later template updates come only through act-update.
  2. 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.py refuses that and creates nothing.
  3. An existing project. A folder that already holds a project — its own docs, a CLAUDE.md, an older AI setup — is taken over with act-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 branch act-adopt without 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.

The setup needs no AI. In a terminal, init.py asks for name, owner, stack, lint and test commands, tools, and languages:

Terminal window
python .act/scripts/init.py --plan # show what would happen, change nothing
python .act/scripts/init.py # turn this clone into the project
python .act/scripts/init.py --target ../my-project # set up a new, empty folder instead
python .act/scripts/init.py --non-interactive # no questions: defaults, open points to the inbox

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

Ten fixed steps, each printed as [n/10]:

  1. Collects the settings: name, owner, languages, stack, commands, tools, mode, feedback, update channel (release or latest, written to docs/ai/config.md § Update), working methods (methods, default none) and the scope profile (profile in § Scope: full for a web project, else standard, decided from the stack; --scope sets it). It notes when the clone is already past the newest release.
  2. Resolves Git: in place it removes origin and rebuilds main; with --target it runs git init if needed.
  3. Checks your Git identity.
  4. Writes your workspace identity (also when .act-local/identity.json exists but lacks identity) and the local import folder .act-local/import/.
  5. Thins the bridges down to the tools you chose.
  6. 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": false unless artifacts: on, and PYTHON_BASIC_REPL=1 under env, so that on Windows an empty heredoc in a Bash call cannot hang on Python 3.13 and later). Skill copies and role bridges that profile or exclude in docs/ai/config.md § Scope leave out are not written.
  7. Appends template blocks to .gitattributes and .gitignore, and keeps .act-local/ out of IDE indexes (excludeFolder in .idea/*.iml, files.watcherExclude in .vscode/settings.json where .vscode/ exists).
  8. In place only: retires the template’s own README (the new one follows the readme-format layout of Formats, standard by 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 --target alike it then creates the project’s own CHANGELOG.md with an empty ## [Unreleased] section, unless changelog in § Formats is release-notes-only or off or the project already keeps a changelog under another name; an existing file is never overwritten.
  9. Writes .act-lock.json (the recorded template source and version) and .act/MANIFEST.json.
  10. 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 .gitignore ignores (an allowlist such as *, !docs/) stays out of the commit, which names it; an ignored CHANGELOG.md is 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.

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.