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 twelve 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 a GitHub Actions OIDC exchange in CI. If you have never signed in on this machine:

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

status answers with the organisation, the project and the repository this checkout reports to. identity: not signed in there is the one thing to fix before expecting anything on the board.

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. Uninstall

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

That removes exactly what the install above wrote: its own files go, and its own entries come out of the files it shares with your editor's other hooks and servers, which are left as they were. A hook TeamFlow did not write is never touched, and uninstalling something that is not there succeeds quietly. --dry-run prints the list without removing anything.

The git hooks are the repository's rather than this tool's, so they come out separately:

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

Each of the three loses the block between # BEGIN teamflow and # END teamflow. A hook file that was nothing but that block goes; one you had already keeps everything else in it.

npx -y github:macleodlabs-ai/teamflow-plugin hooks uninstall --all is the bigger hammer: every tool at once, the git hooks, and this repository's ticket binding.

6. The stages to report

BACKLOG 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.

7. 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. Checked against the vendor’s own hook documentation on 2026-09-18: No hook system, so there is no payload to verify; what matters is that Aider still commits after every edit by default, which is what the post-commit hook rides on.

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.

8. What leaves your machine

TeamFlow manages your AI software factory. It is run by MacleodLabs. Your code stays inside your organisation: the local plugin sends 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