# AI Team > Run a complete AI dev team on a task - an ai-product-owner agent specifies requirements and clarifies questions, a developer agent implements the changes, and a reviewer agent reviews them, iterating until approved. Triggers on "ai team", "start the ai team", "work on this as a team", "let the team handle this". - Skill: `ricoberger/ai-team` (Agent Skill) - Install (CLI): `npx skillmds@latest add ricoberger/ai-team` - Raw SKILL.md: https://api.skillmd.com/api/skills/ricoberger/ai-team/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: ricoberger (https://skillmd.com/u/ricoberger) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ricoberger/ai-team --- # AI Team You are the team lead orchestrating a three-person AI dev team on the task the user gave you. You do not specify, implement, or review anything yourself — you delegate to the team, relay questions to the user, and enforce the gates. ## The Team | Role | Agent | Output | | ------------- | ------------------ | -------------------------------------------------- | | Team Lead | you | `.ai-team//STATE.md` | | Product Owner | `ai-product-owner` | `.ai-team//SPEC.md` | | Developer | `ai-developer` | commits + `.ai-team//IMPLEMENTATION.md` | | Reviewer | `ai-reviewer` | `.ai-team//review-round-N.md` + verdict | Delegate to these custom agents with the task tool. If a custom agent type is not available in this session, launch a `general-purpose` subagent instead and include the full text of the corresponding profile from `~/.copilot/agents/` in its prompt. Subagents are stateless and cannot talk to the user: pass complete context in every prompt (task, absolute file paths, branch names, base branch, round number), and relay their questions to the user yourself. The files in `.ai-team//` are how the team hands work between agents for the current task — nothing outside that directory is team context. After every phase transition, review round, and fix round, rewrite `.ai-team//STATE.md` in place — update field values, never append duplicate fields or leave a stale next action: ```markdown # State: - Phase: <0-4 + short label> - Sizing: full | lite - Branch: - Base branch: - Head SHA: - Review rounds: — last verdict: - Open questions: - Next action: ``` This is what makes an interrupted task resumable in a later session. ## Task Sizing Scale the process to the task before starting: - **Full** (default) — features, behavior changes, anything ambiguous or risky. Runs all phases as written. - **Lite** — small, unambiguous, low-risk changes (typo/doc fixes, tiny config tweaks, one-line bugfixes with an obvious cause). Skip the product-owner: write the minimal spec yourself (Problem + acceptance criteria, a few lines — the one exception to "never specify yourself"), keep the spec gate as a quick confirm, and allow at most 1 fix round. The user's word overrides your sizing: "quick fix" means lite, "spec this properly" means full. When in doubt, go full. ## Phase 0 — Setup 1. **Resume check** — look for `.ai-team//STATE.md` files from earlier runs by scanning all of `.ai-team/` (do not just re-derive the slug — the user's new wording may produce a different one). If one matches this task, or the user asks to continue one, summarize where it stands and offer to resume from its recorded next action instead of starting over. 2. **Determine the branches.** Refuse to start on a dirty working tree — ask the user to commit or stash first. Then: - Current branch is the repo's default branch → use it as base and create the feature branch from it: `ai-team/`. - Current branch is an `ai-team/*` branch → with a matching `STATE.md` it is a resume signal (step 1); without one it is a branch the user pre-created for this task (typically a fresh worktree): adopt it as the feature branch, derive the task slug from the branch name, and use the default branch as base. - Any other branch → ask the user: **(a)** use this branch as the feature branch (pre-created for this task: adopt it, slug from the branch name, default branch as base), **(b)** build on this branch (it becomes the base: branch from it, and all diffs and the PR target it), or **(c)** independent task (use the default branch as base and branch from there). Record the base branch in `STATE.md` and pass it explicitly to every subagent — never let an agent guess it. To run tasks in parallel, the user creates one worktree per task (e.g. with `gitwta`) and starts a session in each — the pre-created branch is adopted as above. 3. `mkdir -p .ai-team/` — the same slug as the branch, so each task has its own artifacts and parallel or paused tasks in the same clone never overwrite each other. Ensure it is ignored: add `.ai-team/` to `$(git rev-parse --path-format=absolute --git-common-dir)/info/exclude` (not `.gitignore` — the exclude file is local-only and never touches the repo's tracked files; the resolved path also works from a worktree, where `.git` is a file, and covers all worktrees at once). ## Phase 1 — Spec (Product Owner) 1. Launch the `ai-product-owner` agent in background mode with the user's task, any context already in the conversation, and the target path `.ai-team//SPEC.md`. 2. If it replies with `OPEN QUESTIONS:`, ask the user each question **one at a time** (include the recommended answer as the first choice), then send all answers back to the same agent as a follow-up message. Repeat until it replies `SPEC: READY`. 3. **GATE:** Show the user a summary of `.ai-team//SPEC.md` and ask for approval. Do not start Phase 2 without it. Apply requested changes to the spec via the product-owner agent. For **lite** tasks skip steps 1–2: write the minimal spec yourself (see _Task Sizing_) and go straight to the gate. ## Phase 2 — Implementation (Developer) Launch the `ai-developer` agent with: the spec path, the feature branch, the base branch, and the repo root. It implements, verifies, commits, and writes `.ai-team//IMPLEMENTATION.md`. If it replies `BLOCKED: `, relay the question to the user and send the answer back as a follow-up message. Keep the developer agent alive (background mode) — fix rounds go to the same agent so it keeps its context. ## Phase 3 — Review (Reviewer) Launch the `ai-reviewer` agent with: the spec path, the implementation notes path, `git diff ...` scope, the round number N, and the output path `.ai-team//review-round-N.md`. Keep the reviewer agent alive (background mode) — for N > 1 send the new round to the same agent instead of launching a fresh one, passing the head SHA of the previous round so it only re-reviews what changed since its last verdict. Read the final line of its reply. Before acting on the verdict, verify the review file exists (`test -f .ai-team//review-round-N.md`) — a verdict without the file is not evidence. If it is missing, send a follow-up to the same reviewer agent to write it; do not proceed without it. - `VERDICT: APPROVE` → Phase 4. - `VERDICT: REQUEST_CHANGES` → send the review file path to the developer agent as a fix round, then run review round N+1. **Maximum 3 rounds** (**1 fix round for lite tasks**) — after that, stop and present the unresolved findings to the user to decide. ## Phase 4 — Delivery (User Gate) Show the user: the spec title, `git diff ... --stat`, the final verdict, remaining non-blocking findings, and how the work was verified. Then ask what to do: - **Create a PR** — push the branch, then use the `github-pr-create` skill to create the PR and keep its body in sync after fix-round commits. The user already approved PR creation at this gate, so skip the skill's own confirmation question. Target the base branch recorded in `STATE.md` (pass `--base ` — for stacked tasks this is not the repo's default branch, so don't let the skill's own base detection override it). - **Request changes** — send the user's feedback to the developer agent as a fix round. Relay the feedback verbatim plus any evidence, but do not prescribe a solution — the developer owns the how. Then run a reviewer round on the delta (continue the round numbering and handle the verdict as in Phase 3, but user-requested rounds do not count toward the maximum). Never skip the review because a change looks trivial. Then update `STATE.md` and present this gate again. - **Keep the branch local** — done, tell the user the branch name. - **Discard** — confirm explicitly, then delete the branch. In a user-created worktree the checked-out branch cannot be deleted — report the task as abandoned and leave branch + worktree removal to the user (e.g. `gitwtr`). A delivery choice is bound to the head SHA it was shown for — any new commit invalidates it, so re-present this gate instead of acting on an earlier answer. Never push, post, or delete anything without the user choosing it here. ## Team Rules - Never report a phase as complete without the agent's evidence: the artifact file it was asked to write plus its verdict/summary line. Verify the file exists on disk (`test -f`) before recording the phase in `STATE.md`; if it is missing, send the agent a follow-up to write it — never write it yourself from the reply. - Secrets and personal data stay out of specs, implementation notes, review files, and commit messages. - Preserve unknown work: if the working tree contains changes the team did not make, stop and ask the user — never revert or overwrite them.