# Init Trimtab

> Use when the user asks for $init-trimtab or wants to inspect a specific repo and install or retune a Trimtab player/coach workflow for that project's actual constraints, tools, and task graph.

- Skill: `hmbown/init-trimtab` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add hmbown/init-trimtab`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hmbown/init-trimtab/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Hmbown (https://skillmd.com/u/hmbown)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hmbown/init-trimtab

---


# $init-trimtab

Use this skill when the user wants to:

- install Trimtab into a specific project
- retune an existing Trimtab setup to match the repo's real workflow
- make the workflow project-local instead of relying on a global-only skill
- inspect repo instructions, dependency graph, issue tracker, and agent surfaces before editing the Trimtab config

## Default Goal

Make Trimtab travel with the repository.

Prefer a checked-in, project-local setup over a user-global-only setup:

- **Claude Code entrypoint:** project command at `.claude/commands/init-trimtab.md`
- **Shared canonical protocol:** `.trimtab/init-trimtab-protocol.md`
- **Codex skill source:** `.codex/skills/init-trimtab/` with registration path `.codex/skills/init-trimtab/SKILL.md`

This keeps the repo's workflow inspectable and versioned with the repo itself.

Default to the thinnest useful installation.

That means:

- prefer adapting existing repo surfaces over creating new ones
- only create missing files when there is no strong equivalent already present
- if the repo already has a task queue, handoff file, issue tracker, or instruction surface, hook Trimtab into it instead of replacing it
- do not create extra workflow files just because the starter repo happens to use them

When a repo uses Linear, the ideal end state is:

- the Linear issue body is the operative prompt
- issue dependencies are the operative graph
- comments and status changes are the durable waterfall surface
- the next task is chosen from the next unblocked issue, not from a fresh bespoke prompt
- local files such as `HANDOFF.md` support the issue flow instead of replacing it

## First Move

1. Identify the target workspace
2. Inspect the repo before editing anything
3. Decide which mode applies:
   - **Bootstrap**: no usable Trimtab workflow exists yet
   - **Protocol upgrade**: workflow exists but needs stricter rules
   - **Retune**: workflow exists and should be adapted to the repo's actual tools and conventions
4. Preserve strong existing instructions instead of flattening them into starter boilerplate

## What To Inspect

Read [references/repo-audit.md](references/repo-audit.md) before you start patching.

At minimum inspect:

- root docs such as `README.md`
- existing `CLAUDE.md`, `AGENTS.md`, `DEPENDENCY_GRAPH.md`, and `HANDOFF.md`
- `.github/` templates and workflows
- repo build, test, and lint entrypoints
- issue-tracker signals such as Linear, beads, Jira, or GitHub Issues
- any existing `.claude/commands/`, `.claude/agents/`, or `.codex/skills/`

## Default Workflow Topology

Default to the safest profile unless the repo already has a better explicit one:

- **Orchestrator / player:** Claude Code
- **Worker sub-agents:** Claude and/or Codex sub-agents as useful
- **Closure verifier / coach:** fresh Codex context

This is a default, not a prison. Preserve a project-specific topology if it is already explicit, coherent, and independently verifiable.

Topology invariant:

- never scaffold `Claude -> Claude` as the default player/coach pattern
- prefer `Claude -> Codex` by default
- allow `Codex -> Codex` when the repo is Codex-led, as long as the coach is a fresh separate Codex context
- treat other non-Claude player -> Codex variants as optional future patterns, not the default

Override conditions:

- Codex is unavailable in the environment
- the user explicitly asks for a different topology
- the repo already has a stronger explicit topology the operator wants to preserve

If you override the default, record the reason explicitly in the protocol or handoff.

Default authority boundary:

- the Codex coach is the only verifier
- the Codex coach is the only actor allowed to touch Linear in the Trimtab loop
- Claude may orchestrate and edit local files, but should not itself verify or post workflow updates to Linear unless the repo explicitly wants a different topology
- worker contexts, including Codex workers, should not directly update Linear; they return evidence to the coach or orchestrator

## Required Outputs

When you initialize or retune a repo, leave these surfaces aligned:

- `CLAUDE.md`
- `AGENTS.md`
- `DEPENDENCY_GRAPH.md` or the repo's real dependency-graph surface
- `HANDOFF.md`
- `.trimtab/init-trimtab-protocol.md`
- `.claude/commands/init-trimtab.md`
- `.codex/skills/init-trimtab/` with `SKILL.md` as the registration target

If the repo does not use one of these exact files, adapt to the repo's real surface and record the deviation.

## Rules

- Do not overwrite existing instructions blindly
- Do not invent a dependency graph if the repo already has one elsewhere
- Do not create a new local dependency graph if the repo already has a real operative task surface such as Linear, GitHub Issues, beads, or an existing handoff/task file
- Do not create duplicate handoff or queue files when the repo already has a strong equivalent
- Do not strip out issue-tracker integration just because the starter is generic
- Do not assume the safest default is always the final topology
- Keep the Claude and Codex entrypoints thin and aligned to the shared protocol file
- If you change the protocol, keep both wrappers consistent with it
- Install the no-self-verdict rule explicitly: review-only or zero-edit batches still go to an external coach before anyone says `PASS` or "no fixes needed"
- If Linear exists, make the issue body, criteria, and dependency edges the primary task packet
- If Linear exists, make the waterfall rule explicit: after a verified issue closes, the player should continue to the next unblocked issue unless the operator reprioritizes
- If Linear exists, make the authority boundary explicit: the Codex coach handles Linear reads/writes and verification; Claude orchestrates unless the repo explicitly chooses another topology
- If the repo already has a rich queue or issue graph, do not spend the session rebuilding it from scratch unless the user explicitly asked for that migration
- Ask clarifying questions only when blocked by missing authority, missing external information, or a genuinely ambiguous mapping between Trimtab and the repo's existing workflow
- If the repo uses Codex through Claude MCP, recommend `approval-policy: never` for bounded worker and verifier packets; the real gate should be issue criteria plus independent verification
- If the repo wants orchestrator-side visibility into live Codex MCP work, consider the optional Trimtab observer bridge; describe it honestly as a local observer surface, not a shared collaboration layer

## Success Condition

The repo should end with:

- one canonical project-local Trimtab protocol
- one Claude Code entrypoint for `/init-trimtab`
- one repo-stored Codex skill source for `$init-trimtab`, plus a clear local registration path
- workflow docs and task surfaces adapted to the actual project rather than left as boilerplate