ai-team

Drop a full AI product team into any project in one command — and keep them in sync as the templates evolve.

ai-team is a CLI that installs a curated set of AI agent definitions, skills, and workflows into your project and tracks them with a manifest so updates are always safe.

What you get

After running init your project gains:

• Specialist agents — requirement analyst, planner, frontend dev, backend dev, code reviewer, tester, documentation writer, and orchestrator — ready to use in your IDE's agent runner
• Shared skills — reusable prompt modules that agents load at runtime
• Team workflows — pre-defined delivery and handoff sequences
• Optional MCP config — wired-up tool servers for your IDE out of the box

Everything is tracked in .agents/manifest.json so the CLI knows exactly what it installed and can update safely without stomping on your customisations.

Installation

npm install -g ai-team
# or
pnpm add -g ai-team

Quick start

# Bootstrap your project (interactive)
cd my-project
ai-team init

# Or go fully non-interactive for CI / onboarding scripts
ai-team init --ide vscode --team web-product --include-mcp --yes

That's it. Open your IDE and your agent team is ready to go.

Verify the install

ai-team doctor

Example output:

✔ manifest found (.agents/manifest.json v0.1.0)
✔ 14 files installed, 0 missing
✔ 0 drifted files
✔ no migration candidates

Staying up to date

When the upstream templates ship improvements, pull them into your project without touching anything you've edited:

ai-team update

The sync engine compares hashes. Files you've modified locally are skipped and reported — never silently overwritten.

Preview before applying

Not sure what will change? Run a dry-run first:

ai-team plan

Example output:

~ .github/agents/backend-dev.agent.md   template changed, will update
  .github/agents/tester.agent.md        local drift detected, skipping (use --force to overwrite)
+ .agents/skills/visual-testing/SKILL.md  new file, will install

Force-overwrite a drifted file

ai-team update --force

Apply a legacy layout migration

If you're on an older install where agent files lived under .agents/teams/, move them to the current layout:

ai-team update --migrate

IDE support

| Flag | Installs agents to | MCP config | | ------------------- | --------------------------- | ------------------ | | --ide vscode | .github/agents/*.agent.md | .vscode/mcp.json | | --ide claude-code | .claude/agents/*.md | .mcp.json |

IDE is prompted interactively when not supplied.

Project layout after init

my-project/
├── .agents/
│   ├── manifest.json          ← install manifest (commit this)
│   ├── skills/                ← shared skill modules
│   ├── teams/web-product/     ← team workflows and README
│   └── custom/                ← your own extensions (never touched by CLI)
│       ├── skills/
│       ├── workflows/
│       └── agents/
├── .github/
│   └── agents/                ← agent entry files (vscode)
│       ├── frontend-dev.agent.md
│       ├── backend-dev.agent.md
│       └── ...
└── .vscode/
    └── mcp.json               ← MCP tool config (if --include-mcp)

Command reference

init

Install the agent team and write .agents/manifest.json.

ai-team init
ai-team init --ide vscode --team web-product --include-mcp --yes

| Flag | Description | | ------------------------------------ | ----------------------------- | | --ide <vscode\|claude-code> | Target IDE / agent runner | | --team <web-product> | Team profile to install | | --include-mcp / --no-include-mcp | Install MCP config | | --target <path> | Project root (default: cwd) | | --yes | Skip prompts, use flag values |

update

Sync installed files to the latest bundled templates.

ai-team update
ai-team update --force      # overwrite locally modified files
ai-team update --migrate    # apply safe legacy path moves

plan / diff

Dry-run: show what update would do without writing anything.

ai-team plan
ai-team diff   # alias

doctor

Validate manifest health, check for missing or drifted files, and preview any available migrations.

ai-team doctor
ai-team doctor --json   # machine-readable output for CI

version

Print the installed CLI version.

ai-team version
ai-team --version

Adding your own agents and skills

The CLI never reads or modifies anything under .agents/custom/. Use that directory freely:

.agents/custom/
├── skills/my-skill/SKILL.md
├── agents/my-agent.md
└── workflows/my-workflow.md

Reference your custom skills from any agent definition the same way built-in skills are referenced.

CI usage

# Check for drift in CI without modifying anything
ai-team doctor --json --target .

# Auto-apply safe updates in a release pipeline
ai-team update --yes --target .

• .agents/custom/workflows/
• .agents/custom/agents/

Update safety model

• Copy-tracked files with local edits are skipped and reported
• JSON assets (like MCP config) are merged structurally
• Use --force to overwrite copy-tracked conflicts

Development

Run tests:

pnpm test

More documentation

• Detailed CLI docs: docs/cli.md
• Architecture and delivery plan: docs/plan.md