ai-team 1.0.0 → 1.0.1

package/README.md

@@ -1,103 +1,196 @@
-# Agent Bootstrap CLI
+# ai-team
 
-Bootstrap and maintain multi-agent template assets in downstream projects with a manifest-driven, safe update workflow.
+Drop a full AI product team into any project in one command — and keep them in sync as the templates evolve.
 
-## What this CLI does
+`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.
 
-- Installs base agent assets and IDE-specific overlays
-- Tracks installed files with `.agents/manifest.json`
-- Updates templates safely (skip local edits by default)
-- Validates install health and reports drift
-- Previews changes and migration moves before applying
+## 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
+
+```bash
+npm install -g ai-team
+# or
+pnpm add -g ai-team
+```
 
 ## Quick start
 
-From this repository root:
+```bash
+# 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
 
 ```bash
-pnpm run cli -- init --ide vscode --team web-product --include-mcp --target /path/to/project --yes
+ai-team doctor
 ```
 
-Then check install health:
+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:
 
 ```bash
-pnpm run cli -- doctor --target /path/to/project
+ai-team update
 ```
 
-## Command reference
+The sync engine compares hashes. Files you've modified locally are **skipped and reported** — never silently overwritten.
 
-### `init`
+### Preview before applying
 
-Install templates and create `.agents/manifest.json`.
+Not sure what will change? Run a dry-run first:
 
 ```bash
-pnpm run cli -- init --ide vscode --team web-product --include-mcp --target /path/to/project --yes
+ai-team plan
 ```
 
-### `update`
+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
+```
 
-Sync installed files to bundled templates using manifest drift detection.
+### Force-overwrite a drifted file
 
 ```bash
-pnpm run cli -- update --target /path/to/project
+ai-team update --force
 ```
 
-Force overwrite for copy-tracked conflicts:
+### 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:
 
 ```bash
-pnpm run cli -- update --target /path/to/project --force
+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)
 ```
 
-Apply safe legacy migration moves:
+## Command reference
+
+### `init`
+
+Install the agent team and write `.agents/manifest.json`.
 
 ```bash
-pnpm run cli -- update --target /path/to/project --migrate
+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.
+
+```bash
+ai-team update
+ai-team update --force      # overwrite locally modified files
+ai-team update --migrate    # apply safe legacy path moves
 ```
 
 ### `plan` / `diff`
 
-Dry-run preview of actions, conflicts, and migration candidates.
+Dry-run: show what `update` would do without writing anything.
 
 ```bash
-pnpm run cli -- plan --target /path/to/project
-pnpm run cli -- diff --target /path/to/project
+ai-team plan
+ai-team diff   # alias
 ```
 
 ### `doctor`
 
-Validate manifest health, missing files, drift, and migration preview.
+Validate manifest health, check for missing or drifted files, and preview any available migrations.
 
 ```bash
-pnpm run cli -- doctor --target /path/to/project
+ai-team doctor
+ai-team doctor --json   # machine-readable output for CI
 ```
 
-## Flags
+## Adding your own agents and skills
 
-- `--ide <vscode>`
-- `--team <web-product>`
-- `--target <path>` (defaults to current directory)
-- `--include-mcp` / `--no-include-mcp`
-- `--force` (overwrite locally modified copy-tracked files)
-- `--migrate` (apply safe legacy moves)
-- `--yes` (non-interactive defaults)
-- `--json` (machine-readable output)
+The CLI never reads or modifies anything under `.agents/custom/`. Use that directory freely:
 
-## Installed layout (VSCode/Copilot)
+```
+.agents/custom/
+├── skills/my-skill/SKILL.md
+├── agents/my-agent.md
+└── workflows/my-workflow.md
+```
 
-- Shared assets: `.agents/skills/**`, `.agents/teams/web-product/**`
-- Agent entry files: `.github/agents/*.agent.md`
-- Optional MCP config: `.vscode/mcp.json`
-- Install manifest: `.agents/manifest.json`
+Reference your custom skills from any agent definition the same way built-in skills are referenced.
 
-## Template source of truth
+## CI usage
 
-- Agent template definitions are canonical in `src/agents/definitions/*.yaml`
-- Template pack metadata and resolution are canonical in `templates/bootstrap/manifest.json`
-- Installed files such as `.github/agents/*.agent.md`, `.vscode/mcp.json`, and `.agents/**` are generated outputs
+```bash
+# Check for drift in CI without modifying anything
+ai-team doctor --json --target .
 
-Project-owned customization paths (not parsed by CLI):
+# Auto-apply safe updates in a release pipeline
+ai-team update --yes --target .
+```
 
-- `.agents/custom/skills/`
 - `.agents/custom/workflows/`
 - `.agents/custom/agents/`
 

package/package.json

@@ -1,23 +1,18 @@
 {
   "name": "ai-team",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "AI agent team management CLI tool",
   "type": "module",
   "main": "src/cli.js",
   "bin": {
     "ai-team": "src/cli.js"
   },
-  "scripts": {
-    "test": "node --test",
-    "ai-team": "node ./src/cli.js"
-  },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.28.1",
   "dependencies": {
     "@inquirer/prompts": "^8.2.1",
     "chalk": "^5.6.2",
@@ -26,5 +21,9 @@
   },
   "devDependencies": {
     "mustache": "^4.2.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "ai-team": "node ./src/cli.js"
   }
-}
+}