Skip to content

Layers and overrides

Layer Content Changed by
.act/ Rules, coding rule sets, working methods, formats, skills, agent roles, hooks, scripts, tier table An update replaces it as a whole. You never edit it.
docs/ ai/ (config, rules, board, inbox, tasks, journal) and project/ (your documentation) You and the assistant. An update never overwrites your content; it refreshes unedited generated files, files findings in the inbox and runs migrations.

.act-local/ stays on your machine: local state and caches (the hooks’ compiled-module cache lives in .act-local/pyc/, throwaway material in .act-local/tmp/). The session-start check act-local-tidy clears old throwaway material from it (see Configuration); init and update also keep JetBrains and VS Code from indexing it. The generated board is docs/ai/board.md (gitignored) in the default board: docs mode and lives in .act-local/ only in local mode. In Claude Code, a hook blocks writes into .act/.

A project-specific version of anything under .act/ goes to docs/ai/local/<same path>. The same relative path is looked up there before .act/, so a rule file, a skill folder (docs/ai/local/skills/<name>/), or an agent (docs/ai/local/agents/<name>.md) shadows the template’s. docs/ai/local/ is yours: the assistant writes there only on your explicit instruction. A skill or agent you add with act-load-settings lands there too; one you create by hand there gets its tool copies at the next session start (default session-start-refresh: block) or update. Working methods follow the same path (docs/ai/local/methods/<name>.md). The formats for commit message, changelog, release notes and README are the one exception: a file docs/project/formats/<name>.md replaces the template’s file of that name completely (act-export-settings --with-formats carries it to another project, act-load-settings writes it back), see Configuration.

An override whose counterpart under .act/ has been renamed or removed by the template silently has no effect any more. act-doctor reports such a file under docs/ai/local/ with the most similar name under .act/ (rule overrides, roles and your own skills are left out); a local skill with the name of a template skill is a finding too, until you keep it with python .act/scripts/doctor.py --accept skill:<name> (own-rules-review); update.py shows the line in the report of its doctor run.

A package adds rules, coding sets, skills, roles, topics, scripts and check modules to a project without editing .act/ (see the act-packages skill). Its rules load in this order: the package’s pre-template/ files, then .act/, then the package’s post-template/ files, then docs/ai/local/. A package’s import lines sit in marked blocks of docs/ai/rules.md, and python .act/scripts/rules.py --imports shows the resulting order. A package takes effect from the next session.

docs/ai/rules.md imports the rule files and lists every rule with a checkbox. A checked rule applies; an unchecked rule is off, even though its text is loaded. Drop an import line to switch off a whole area. A rule file excluded through exclude in docs/ai/config.md (Scope) keeps its line, but the session start turns the import into a bare path, so Claude Code no longer loads it. Your own text goes in the sections at the end of the file:

  • ## Overrides: - replaces `R-id`: <your wording>. The line replaces the whole text of that rule, checked or not.
  • ## Own rules: - `R-your-id`: text or a bare bullet, in addition to the template’s rules. Keep them short: act-doctor warns when the own rules of docs/ai/rules.md and docs/project/coding_rules.md together pass the own-rules-budget check (default 6000 characters).

python .act/scripts/rules.py --list --area core shows every rule with its state, overrides as [~] and own rules as [+] (without --area core it lists the coding sets); --validate reports text it could not read. Path-bound rules of Claude Code under .claude/rules/**/*.md show up in --list with their paths: patterns; --validate warns about a pattern that matches no project file and a file without paths:.

The main session loads CLAUDE.md, which imports docs/ai/rules.md and through it the shared rules, the coding rules and the orchestrator rules. A worker does not load CLAUDE.md; a SubagentStart hook gives it the same text without the orchestrator rules (see Roles). The three git rules R-safe-no-secret-diff, R-safe-git-reset and R-safe-git-discard sit at the end of the orchestrator rules, since only the main session commits or changes the working tree; workers do not load them. A rule your project switched off (unchecked, or its import removed) stays off for a worker too. If you edited docs/ai/rules.md, an update moves their checkbox lines along with them, mark and reason unchanged, so a rule you switched off stays off. The update and the session start also enter rules the template added since (for example R-docs-order) into an edited docs/ai/rules.md: a checkbox line per new rule, and a new rule file as an import block at the end of its section. Your own text, unchecked boxes and imports you removed stay untouched, and a layer you import nothing from is left alone; .act-lock.json records what was offered, so a line or import you removed does not come back. What cannot be entered safely is named by python .act/scripts/rules.py --add-missing, and rules.py --validate and the doctor report rule files not yet imported and rules the template no longer has. When a rule moved to another file, rules.py also reports a moved rule that lands in a file your project shadows with its own copy under docs/ai/local/rules/ lacking that rule (the rule would not load), and an ID listed twice in one block (only the last line counts; --validate flags it too). python .act/scripts/rules.py --worker shows what a worker gets, --imports what the main session loads, with each file’s size in characters and a total split into the template’s share and the project’s. The rules that a hook checks mechanically are kept short in the rule file: the ban or duty and the name of the check stay, while what the check recognises, its limits, its switch and its syntax stand on the checks page.

docs/project/coding_rules.md works the same way for coding rules. Each line - [x] use: @../../.act/coding/<set>.md (checked) or - [ ] use: .act/coding/<set>.md (unchecked) switches a set on or off, with its groups (CR-<set>-<group>) listed below and each individually checkable. init presets the boxes from the stack it detects, and stack in docs/ai/config.md is where you correct it. The same sections for overrides and own rules apply. Sets exist for, among others, Python, TypeScript, Vue, Nuxt, Tailwind, PHP, Java, Go, Rust, Kotlin, C, C++, PowerShell, Docker, CI, CSS, JavaScript and React. When an update brings a new set, it appears unchecked in the file; a new group of a checked set appears checked. Existing lines, boxes and your own rules stay as they are. update.py --plan previews the sets and groups an update would enter; python .act/scripts/rules.py --add-new-coding enters them later. While docs/project/coding_rules.md has uncommitted changes, the update enters nothing (they would have gone into the update commit), says so in step 6 and in the closing notes, and names the command to run after committing. The working methods you switch on with methods are written into this file as imported sets too.

docs/ai/config.md steers workflow, checks, roles, and languages. Its ## Roles table overrides the tier, reasoning, model (Claude Code), or Copilot models of one role. See the configuration reference, the rules reference, and the coding rules reference.

An update can replace .act/ without a merge, because the project never edited it. Your decisions sit in files the update does not own. If an update finds a hand edit in .act/ anyway, you choose: rescue moves it to docs/ai/local/, discard drops it, abort stops the update.