Skip to content

Introduction

The agentic coding template, short act, is a set of files you put into a project so that your AI coding assistant works to a fixed, inspectable method. It contains rules, skills, sub-agent roles, hooks, and scripts. It works in a new project and in one that already exists.

  • A division of labor. You set goals and decide. The main assistant, the orchestrator, plans, reviews, and commits. It hands bounded assignments to specialized workers. See Roles.
  • A process with evidence. An idea gets a concept with options before it is built. A result counts as done only with a test run, a commit, or an outside call as proof.
  • State in the repository. Tasks, backlog, questions, inbox, and journal sit in docs/ai/, so every session can continue from the board. A chat message that begins with todo:, note: or idea: is filed by a hook without a model turn, and /act-config shows and sets the settings in docs/ai/config.md the same way.
  • Recurring work as skills. A skill is a plain SKILL.md that any assistant can follow, for example act-bug, act-commit, act-release. /act <name> shows a template skill’s instructions in full, with or without its act- prefix (/act version shows act-version); act-version, act-info (which project a session works in and its state), act-export-settings and act-load-settings start only as typed slash commands. A hook answers /act-info and /act-version itself, without a model turn; /act-version prints three lines, --all the full list of releases. See the skills reference.
  • Text in your format. The commit message, the changelog, the release notes and the README follow a format you can pick or replace per project (act-commit and act-release read it, act-export-settings --with-formats carries it to another project), and optional working methods such as test-first add rules for how the assistant works. See Formats and Scope.

Teams and solo developers whose project lives longer than one session: work is handed over between sessions or people, existing code gets changed, or a mistake such as a leaked secret would be expensive.

  • Not a framework or a library. Nothing from it ends up in your build or at runtime.
  • Not free of cost. The rules load at the start of every session, roughly 7,000 to 8,000 tokens with one coding rule set, and about half as much for each sub-agent, which skips the orchestrator rules. The assistant also does more per task: tests as evidence, a review, a journal entry. For a one-off script or a throwaway prototype that costs more than it saves.
  • Not a guarantee in every tool. Mechanical enforcement through hooks exists only in Claude Code (see below).

A project has two layers that never mix.

Layer Where Who owns it
Template .act/ The template. Replaced as a whole by an update, never edited in the project.
Project docs/ai/ (working state), docs/project/ (your documentation) You. An update never overwrites your content.

Around them sit the small files each tool reads (CLAUDE.md, AGENTS.md, .claude/, .agents/skills/) and .act-local/, which stays on your machine. A project version of a template file goes to docs/ai/local/<same path> and wins. Details: Layers and overrides.

Tool Reads What it gets
Claude Code CLAUDE.md, .claude/ Everything: rules by import, skills by name, sub-agent roles with a model and effort tier, hooks, a status line, the board at session start.
Codex, GitHub Copilot, Cursor AGENTS.md, .agents/skills/; Copilot also .github/agents/ Rules and skills as instructions. No hooks, so nothing is enforced mechanically. With copilot in tools, Copilot also gets the roles as files under .github/agents/; Codex and Cursor have no sub-agent roles.
Gemini CLI GEMINI.md, .agents/skills/ The skills. A project has no GEMINI.md yet, so point Gemini CLI at AGENTS.md in its settings.
Any other assistant none Tell it to read docs/ai/rules.md. Every skill is a plain SKILL.md.

The tools in use are the tools key in docs/ai/config.md, default claude-code. Every project gets AGENTS.md and the skill copies under .agents/skills/.

Python 3.9 or newer, standard library only, for the setup, the scripts, and the hooks, and Git 2.25 or newer. Next: start a new project or adopt an existing one.