TeamFlow in Aider

1. Install

npx -y github:macleodlabs-ai/teamflow-plugin skills install --for aider

That writes:

• CONVENTIONS.md — the skills and the reporting instruction, with no MCP tool mentioned

Add --scope user to install for every project on this machine, or --dry-run to see the file list without writing anything. Re-running it replaces TeamFlow's block and leaves the rest of each file alone.

Aider has no hook a local command can subscribe to, so the reporting comes from this repository's own git hooks:

npx -y github:macleodlabs-ai/teamflow-plugin hooks install --git

That writes three marked blocks into .git/hooks: post-commit, post-merge and pre-push. Each one exits 0 whatever TeamFlow answers, so a TeamFlow outage can never block a commit or a push.

2. The skills you get

The same ten the Claude Code plugin carries, generated from the same SKILL.md files. This tool has no skill loader, so they arrive as sections of the rules file the installer writes rather than as files nothing would read; ask for one by name and the agent runs its command.

Each one wraps a github:macleodlabs-ai/teamflow-plugin subcommand, so the skill and the shell command are the same thing. Inside Claude Code they are /teamflow:login, /teamflow:status and so on.

3. Signing in

npx -y github:macleodlabs-ai/teamflow-plugin report uses whatever credential the Claude Code plugin already resolved: a session from teamflow login, else TEAMFLOW_API_KEY, else a GitHub Actions OIDC exchange in CI. If you have never signed in on this machine:

npx -y github:macleodlabs-ai/teamflow-plugin login

4. Loading the conventions

aider --read CONVENTIONS.md

or in .aider.conf.yml:

read: CONVENTIONS.md

--read is preferred over adding the file: it marks it read-only and caches it under prompt caching.

Adding the test gate to the push hook

npx -y github:macleodlabs-ai/teamflow-plugin hooks install --git above reports the commit, the merge and the push. It cannot know whether your tests passed, so if the gates matter, run them from the same hook:

# .git/hooks/pre-push
#!/bin/sh
key=$(git branch --show-current | grep -oE '[A-Z][A-Z0-9]+-[0-9]+') || exit 0
[ -n "$key" ] || exit 0
if npm test --silent; then
  npx -y github:macleodlabs-ai/teamflow-plugin report --issue "$key" --stage LOCAL_TEST --status success \
    --summary "Local suite green before push"
else
  npx -y github:macleodlabs-ai/teamflow-plugin report --issue "$key" --stage LOCAL_REWORK --status failed \
    --rework-from LOCAL_TEST --summary "Local suite failed before push"
  exit 1
fi

The reporter exits 0 on a refused, queued or unreachable service, so a TeamFlow outage can never block a push. Only a bad argument exits non-zero, and it names the argument.

5. The stages to report

JIRA is the thirteenth: the ticket exists and nothing has started. Statuses are running, success, waiting, blocked, failed and idle. This is the same vocabulary the Claude Code plugin derives, so a ticket moved from here sits in the same column as one moved by Claude.

6. What this is not

Aider has no agent hooks, so TeamFlow installs git hooks: commits, merges and pushes report by themselves; test and audit gates report when the test command runs through teamflow. Aider has no hook system, but it commits after every edit by default, so the git post-commit hook tracks an Aider session closely.

A commit is coarser than a tool call, so the board moves in steps rather than continuously. The rules the installer writes are there as well and the agent may report in between, but the git hooks are the half that does not forget, and they are the half worth wiring first.

Aider cannot call a tool at all. The conventions block tells it to run a command or suggest one, and whether that happens is up to the model and the person at the keyboard.

7. What leaves your machine

TeamFlow is a delivery map for Jira, Linear and GitHub issues, run by MacleodLabs. Reports carry derived state only: a ticket key, a stage, a status, a short summary and evidence links. Prompts, diffs, source code, commands and logs are never sent and are rejected before they are charged.

• Every client
• llms.txt
• Capabilities
• The reporting contract, in full