Content
# tackroom
**One tack room for all your agent harnesses.**
If you work across more than one AI coding tool — Claude Code today, Codex
for a second opinion, OpenCode on the server, whatever ships next month —
you have the same problem every multi-horse stable has: the gear multiplies.
Skills copied into four config dirs, MCP servers registered four different
ways, operating instructions that quietly fork per tool, API keys sprinkled
across dotfiles.
A tack room is where a stable keeps every harness, saddle, and bridle:
one room, maintained once, fitted to any horse. That's this repo — a single
source of truth for **skills, subagents, slash commands, MCP servers,
operating instructions, env vars, and launchers**, wired identically into
every harness by one installer and verified by one doctor.
## The method
1. **Canonical, tool-neutral content.** Skills live once in `skills/`,
written without tool names or machine paths (`tack lint` enforces it).
Shared operating instructions live once in `AGENTS.md`.
2. **Render, don't fork.** Tool-specific formats are *generated*: one MCP
registry (`mcp/servers.json`) renders into Codex TOML, an OMP
`mcp.json`, an OpenCode fragment, and `claude mcp` registration
commands. You never hand-edit four configs again.
3. **Adapters when a tool truly differs.** `adapters/<tool>/<skill>/`
shadows the canonical skill for that one tool. Rare by design.
4. **Private overlay for your content.** The engine is public; your skills,
projects, and credentials live in a second private repo with the same
layout, merged in at install time — overlay wins. `git pull` upstream
improvements without ever sanitizing your history. See
[docs/overlay.md](docs/overlay.md).
5. **A closed verification loop.** `tack install` is idempotent and backs
up anything it replaces; `tack doctor` re-derives the whole build in a
tempdir and diffs — stale links, missing frontmatter, tracked secrets,
wrong permissions all turn the light red. Git hooks re-install and
re-verify after every pull.
## Setup
Prereqs: `bash`, `jq`, `git`, `rg`, plus whichever harnesses you use.
```bash
git clone https://github.com/staz6/tackroom ~/tackroom
cd ~/tackroom
cp env/.env.example .env && chmod 600 .env # fill in what you need
./scripts/install.sh all
echo 'source "$HOME/tackroom/shell/bashrc.snippet.sh"' >> ~/.bashrc
```
Open a new terminal and run `tack doctor` — it must print `all green`.
The clone can live anywhere; every path is derived, nothing is hardcoded.
## Daily use
| Command | What it does |
|---|---|
| `tack install [tool\|all]` | assemble + wire everything (idempotent) |
| `tack doctor` | verify links, skills, env hygiene, build freshness |
| `tack render` | re-render MCP configs after editing the registry |
| `tack new-skill [--overlay] <name>` | scaffold a skill |
| `tack lint` / `tack catalog` | lint skills / regenerate the catalog below |
| `tack overlay [<path>]` | show or set your private overlay |
| `project id\|info\|env\|list` | resolve project context from the cwd |
| `advised claude\|codex ["task"]` | supervised worker TUI — the other model family advises |
| `advisor --to claude\|codex "<packet>"` | ask the other model for a read-only verdict |
## Supported harnesses
| Tool | Skills | Instructions | MCP |
|---|---|---|---|
| **Claude Code** | `~/.claude/skills` → build farm | `~/.claude/CLAUDE.md` | `claude mcp` user scope, auto-registered |
| **Codex** | per-skill links in `~/.codex/skills` | `~/.codex/AGENTS.md` | managed block in `config.toml` |
| **Oh My Pi** | per-skill links, adapter-aware | `~/.omp/agent/AGENTS.md` | rendered `mcp.json` |
| **OpenCode** | via Claude-compat path | `~/.config/opencode/AGENTS.md` | rendered fragment, manual merge |
Adding a harness is a self-contained plugin — two small scripts, no core
changes. See [docs/adding-a-tool.md](docs/adding-a-tool.md).
## The advisor workflow
One model does the work; a model from the *other* family sits behind it
with **read-only** repo access, judging direction at defined checkpoints
(direction → plan → final) and answering in a fixed format:
`VERDICT: CONTINUE | ADJUST | STOP`, plus risks and concrete steering.
Cross-family pairing is the point — different training breaks shared blind
spots.
Start a supervised session with `advised claude` or `advised codex`, or
checkpoint manually from any session with `advisor --to claude|codex
"<packet>"`. The advisor runs headlessly in your repo — sandboxed read-only
for codex, a read-only tool allowlist for claude — and every verdict is
appended to a gitignored audit log. Pin advisor models via `ADVISOR_*`
vars in `.env`; unset means each CLI's own default. Protocol:
[skills/advisor/SKILL.md](skills/advisor/SKILL.md).
## How to add a skill
1. `tack new-skill <name>` (add `--overlay` for private skills) — creates
`skills/<name>/SKILL.md` with frontmatter: `name:` plus a
trigger-oriented `description:` (*when* to use it, not what it is).
2. Write the method as numbered steps with an explicit exit condition.
Tool-neutral: no TUI names, no machine paths — `tack lint` enforces it.
3. `tack install` on other machines after pulling = done everywhere.
## How to change MCP servers
1. Edit `mcp/servers.json` (or your overlay's copy — same shape, deep-merged,
overlay wins). Each server names which `tools` receive it.
2. `tack install` — renders every tool's native format into `build/mcp/`
and applies it. Never edit rendered output.
For stdio servers that need API keys, point `command` at a wrapper script
that reads the gitignored root `.env` at spawn time
([mcp/bin/example-wrapper.sh](mcp/bin/example-wrapper.sh)) — keys never
appear in rendered configs and never need to be exported shell-wide.
## Projects
`projects/registry.json` maps directories to projects; each project gets a
`PROJECT.md` context card (stack, invariants, verification commands) that
agents load at the start of work via `project info`, and gitignored env
profiles loaded per-invocation via `source "$(project env dev)"`. Your real
registry lives in your overlay.
## Security posture
- Secrets: one gitignored `.env` (chmod 600, documented by
`env/.env.example`), per-project profiles gitignored, gitleaks +
shellcheck + skill lint in CI, doctor checks permissions and tracked-file
leaks on every run.
- `.env` is **not** exported into every shell by default — wrapper scripts
read it at spawn time. Opt in with `TACK_EXPORT_ENV=1` if you want it
global.
- Permission prompts stay **on** by default. If you accept the tradeoff of
running harnesses without approval prompts, `TACK_YOLO=1` adds the
skip-permission aliases — read what that flag does before setting it.
## Starter skill catalog
The engine ships with a small, tool-neutral core: an engineering operating
method (`principles*`), plan-only artifacts (`plan`), independent critique
(`second-opinion` + `file-map`), and project context (`project-context`).
Your own skills go in the overlay — or replace these entirely.
<!-- CATALOG:START -->
- **`advisor`** — Two-model advisor workflow for planning and review — the current model does the bulk of the work while a model from a different family sits behind it with read-only repo access, judging direction at defined checkpoints and steering when needed.
- **`file-map`** — Build a compact file-map context packet — a directory tree with marked relevant files, targeted code excerpts, tech stack, and instructions — so an external model can review repo work from a single attached file.
- **`plan`** — Create a plan-only implementation artifact when the user wants a feature mapped into exact file changes without editing the source tree.
- **`principles-implement`** — Use when writing or modifying code.
- **`principles-plan`** — Use when designing an implementation, migration, or investigation strategy before acting.
- **`principles-review`** — Use when reviewing a diff, commit, PR, or design.
- **`principles-search`** — Use when locating anything — code, config, docs, or the reason a system behaves the way it does.
- **`principles`** — Engineering operating method — index of the principles skill set.
- **`project-context`** — Resolve which project the current directory belongs to and load its context card and environment credentials.
- **`second-opinion`** — Get an independent high-reasoning critique of a candidate answer, plan, patch, diagnosis, or review before finalizing.
<!-- CATALOG:END -->
## License
MIT
