TacT Agent Kit

Good engineering takes tact.
A guide for developers and agents to make sound decisions, deliver working results,
and keep important choices visible.

Get started · Collaboration · Agent entry

The idea

TacT takes its name from tact: a sense of proportion and consideration in how people work together. It gives engineering delivery and the developer's interaction experience equal weight. The agent should advance the work and provide evidence, while the developer can observe, learn, and guide important choices when they still matter.

Install and initialize

Requires Python 3.11 or newer. The CLI has no runtime dependencies. The distribution name is tact-agent-kit; the executable is tact. After the first PyPI release, install with:

uv tool install tact-agent-kit

Before that release, or when developing locally, install from this checkout with uv tool install .. Then preview and initialize a project:

tact --version

# Preview first, then initialize an existing project directory.
tact init /path/to/project --dry-run
tact init /path/to/project

# From inside the target project, the path defaults to the current directory.
tact init

The project can use any language; it does not need a Python environment. TacT installs the bundled Markdown locally without fetching rules during initialization:

your-project/
├── AGENTS.md                 # Existing text plus a marked TacT reading instruction
├── .tact/
│   ├── AGENTS.md             # Shared Kit entry
│   ├── LICENSE               # MIT license for the shared Kit
│   ├── core/                 # Shared topic guidance
│   ├── project/
│   │   ├── README.md         # Guide for project-owned notes and supplements
│   │   └── notes.md          # Project-owned notes, with a short introduction
│   └── manifest.json         # Package version, source URL, and shared-file hashes
└── .agents/skills/tact/
    ├── SKILL.md              # Discoverable entry pointing to this project's Kit
    └── agents/openai.yaml    # Codex UI name, description, and starting prompt

Review and commit AGENTS.md, .tact/, and .agents/skills/tact/ with your project. Put local constraints and supplements in .tact/project/; files already there are preserved. Existing root-level core/ or project/ directories and other skills are left intact. The root entry tells the agent to read the Kit and project notes before substantive work, and establishes .tact/ as the base for the Kit's relative paths.

Repeated initialization with the same package leaves matching files untouched and restores missing files. --dry-run lists proposed writes and shows the root entry diff without creating files or directories. Existing shared files, version metadata, or a TacT entry block that differ cause initialization to stop with differences for review. There is no implicit upgrade or force-overwrite option.

TacT checks for conflicts before writing. It also rejects symbolic links at managed paths and a nonempty root AGENTS.override.md, which would hide the normal entry in Codex. Resolve those conditions explicitly before retrying. If a filesystem error interrupts writing, the command reports that partial files may remain; inspect them before retrying. Matching files are safe to reuse.

Initialization preserves existing instructions but does not interpret conflicts between their meaning and the Kit. Check actual agent loading and behavior using the adoption guide. Installing a newer CLI does not change any initialized project.

Select TacT as a skill

Starting with version 0.1.3, initialization also installs one project-local tact skill. It directs the agent to this project's .tact/ entry and notes, including when the working directory is a nested folder. The full guidance stays in .tact/; the skill is an additional entry alongside the root AGENTS.md reading instruction.

In Codex CLI or the IDE extension, use /skills or type $tact to select it. In clients with a skill selector, look for TacT Agent Kit. Codex detects local skills automatically; restart it if the new skill does not appear. The exact selector UI depends on the client; installing a skill does not register a separate built-in /tact command. See the official skill documentation for discovery locations and invocation.

For a project initialized with an older release, upgrade the installed CLI and run tact refresh as shown below to add the skill. Both skill files are tracked by .tact/manifest.json, so local edits and conflicting files are reported before any writes. Keep project-specific guidance in .tact/project/ instead of editing the shared skill. Installing only the skill folder globally is not supported: its links expect the project's .tact/ snapshot.

Refresh an initialized project's documents

tact refresh applies the documents bundled with the installed TacT package to a selected project. It does not download or upgrade the CLI. After installing a newer package, refresh a project's snapshot explicitly:

# Reinstall from your TacT checkout while developing locally.
uv tool install --reinstall /path/to/TacT
tact --version

tact refresh /path/to/project --dry-run
tact refresh /path/to/project

refresh compares each shared file with its recorded installation hash in .tact/manifest.json. Files that still match that baseline can be replaced with the bundled version. A file already matching the new bundle is also accepted, allowing an interrupted refresh to resume. Local changes or an untracked file occupying a new shared path stop the entire plan before any writes; the command shows the differences for review. A missing or invalid manifest also stops the refresh. Files missing from the new package require manual review; this command does not remove them automatically.

Project guidance is preserved. The only existing project file refreshed automatically is notes.md when it exactly matches a known untouched generated template, including the original source-only template. This adds the introduction and refreshes its version line. Once notes have been edited, they remain unchanged; the manifest is the authoritative record of the currently installed package, even if custom notes retain an older source line.

The preview shows all proposed file differences. Replacements are atomic per file, with the manifest written last. The entire refresh is not a filesystem transaction: if a write fails, inspect the reported partial changes before retrying. Repeating a completed refresh makes no changes.

Find your way

The shared Kit is AGENTS.md plus core/. Each adopting project owns its project/ layer inside the Kit root. CLI installations record their package version and shared-file hashes. Manual copies should use files from one Git commit and record that commit in the adopting project's notes.

Develop and build

# Reinstall so tests use the current bundled Markdown as well as current code.
uv run --reinstall-package tact-agent-kit python -m unittest discover -s tests -v

# Build the source distribution, then build its wheel.
uv build

Edit shared guidance at AGENTS.md, core/, and project/README.md, and the skill at skills/tact/. The skill's relative links target its installed location under .agents/skills/tact/. Hatchling includes these sources in the installed tact_resources namespace; no second editable copy is maintained. The source repository's project/notes.md and project/verification.md are not distributed as adopting-project defaults. When editing guidance during development, reinstall the package to refresh the bundled resource snapshot, including for editable installs.

The build produces a source archive and wheel in dist/. You can install a built wheel with uv tool install /absolute/path/to/the.whl. Both distributions include the MIT license. Initialization and refresh also include it in .tact/LICENSE alongside the shared guidance.

Publish a release

GitHub Actions handles publishing through PyPI Trusted Publishing. The publishing workflow builds the source distribution and its wheel, checks metadata and README rendering, and runs the CLI tests against the installed wheel. Pushes to main and pull requests run these checks. Publishing a GitHub Release also uploads the tested distributions to PyPI; ordinary commits do not publish a package.

Before the first release, enable two-factor authentication on your PyPI account and add a pending publisher in account Publishing:

Use the pypi GitHub environment for this publishing job. No PyPI API token or repository secret is needed. A pending publisher creates the PyPI project on its first successful publication; registering it alone does not reserve the name.

For each release, update the version in pyproject.toml and uv.lock, commit the intended files, and publish a GitHub Release with the matching v tag, such as v0.1.3. The tag must point to the commit containing those files and the workflow. The workflow refuses to publish if the tag differs from the package version. Use a new version for later changed distributions. After the workflow succeeds, verify installation from PyPI with uv tool install --reinstall tact-agent-kit.

License

TacT is distributed under the MIT License.

Source and migration

The migration record explains how the Kit was split from the complete authoring source, what was verified, and what remains to be tried. The English baseline is preserved for comparison and fallback.