--- name: build-a-team-of-claude-code-agents description: Build a small team of Claude Code subagents (planner, finisher, deployer, sweeper) with a shared to-do board, narrow tools and a human gate. Use when a reader wants agents that build, deploy and check projects without chaos. license: CC BY 4.0. Free to use and share with credit to technologytips.blog. metadata: publisher: technologytips.blog article: https://technologytips.blog/articles/ai-coding-agent-team-build-deploy-fix/ article_title: "Run a team of AI coding agents without chaos: our Claude Code playbook" published: 2026-11-12 platforms: [mac, linux, windows] needs: [claude-code] risk: high version: 1 sha256: pending --- # Build a team of Claude Code agents *An AI Fix file from technologytips.blog. Give this file to your AI assistant and say: "Read this file, then walk me through it one step at a time." It works on your own computer, and it asks before anything that can't be undone.* ## What this fixes You have projects that get written but never reach a live address, or that break without anyone noticing. This file helps you build a small team of Claude Code subagents with clear jobs, a shared to-do board and hard limits. It will not promise a result, and it will not give any agent your payment or customer-messaging tools. ## Read this first (safety) - Never ask me to paste a password, recovery code, secret key, 2FA code or private key into this chat. If a step needs one, tell me to type it only into the official app or website. - Before any step that deletes, overwrites, signs out, resets or uninstalls anything, stop, tell me exactly what will happen, and wait for me to say yes. - Make or confirm a backup before changing anything you can't undo. - Only use official apps, official download pages and official documentation. Never suggest cracked software, unofficial installers or scripts from unknown sources. - Never turn off a security feature (encryption, 2FA, firewall, antivirus, FileVault, BitLocker) permanently. If a fix needs it off for a moment, say so and turn it back on. - If anything looks different from these steps, stop and tell me instead of guessing. - This file is general help, not professional support. For account recovery, the company that runs the account is the only real authority. - Agents act with my accounts. Give each agent the fewest tools it needs. Keep deploys, money and customer messages behind my approval. - Use names of environment variables only. Never write a secret value into a file, a log or this chat. This file is marked risk high because agents that can push code and deploy can change things that are live. The steps keep a person in charge of the first live release. ## What you need - A computer with a terminal, and a project folder with your code in it. - A GitHub account and the gh command-line tool, signed in with `gh auth login` (as of November 2026). - A small database, such as a hosted free tier, and a place to host finished work. - About an afternoon for a first pass. - Claude Code installed from the official Claude Code docs: https://code.claude.com/docs/en/sub-agents (see the site's /start-here/ page for the install steps). Start it in a plain, empty folder, not your home folder, and use the approval mode that asks before it runs anything. ## Instructions for the AI You are helping one person build a small agent team on their own computer, using only the steps and sources in this file. Be kind and patient. Say it is not their fault. Go one step at a time and wait for them to say it is done. Read every command aloud in plain words before they run it. Never run a command that deletes, overwrites, moves, signs out, resets or uninstalls without their yes. If your answer would differ from this file, say so and ask. Say "as of November 2026" when you give a menu path or setting, because they change. If something does not match what they see, stop and help them describe it, word for word. ## Questions to ask first Ask these a few at a time, in plain words. If the answer changes the steps, say how. 1. Which projects do you want the team to handle, and where does each one go live? 2. Is each project already in a git repository, and is it pushed to GitHub? 3. Do you have a small database you can use for a to-do board? 4. What has gone wrong before: stuck deploys, unpushed work, jobs that fail without a sound? ## Steps 1. **Make a safe place first.** Ask me to commit everything in the project. Confirm it is committed before going on. This is the backup step for everything below. 2. **Push to a private repository.** Create a private repository from the local folder with gh. This copies my code to GitHub (asks before running). ``` gh repo create my-project --private --source=. --push ``` 3. **Build the board.** Help me make three things in my small database: a builds table (a key, a stage, an owner agent, a next action, a blocked reason, a repo address, a live address and a health result), an event log, and a queue view sorted by priority with blocked rows last. Show me the plan before you create anything. 4. **Write one agent file per role.** Roles: a planner, a finisher, a deployer and a sweeper. Save each in `.claude/agents/` as a markdown file with YAML frontmatter (as of November 2026). Give each a one-sentence job, an input rule (it receives exactly one build key), a numbered procedure and a short "hard rules" list. Show me each file before saving it. 5. **Set tools per agent.** In each file's frontmatter, list only the tools that agent needs. The planner gets read and write on the database only. The deployer gets a shell and git. Nobody gets payment or customer-messaging tools. Before removing a tool, ask me what the agent relied on. 6. **Limit work in progress to one.** Tell the planner not to dispatch a new build while one is mid-flight. 7. **Split "deployed" from "verified".** The deployer may set a build to live after a health address answers with a success code. Only a different agent, or I, may set it to shipped. 8. **Write the sweeper's runbook.** Save it as a separate markdown file the sweeper reads first. List each check with its exact command. Give each finding a fingerprint, so a rerun updates a ticket instead of copying it. 9. **Add the git rules.** The sweeper may push only non-default or local-only branches, as fast-forwards. A default branch in a repo with automated checks is a deploy, so I decide. Diverged repos and missing remotes are mine to decide. Never force-push, merge or delete a branch. 10. **Share the settings.** Help me put permission rules (allow, ask, deny) and any hooks in `.claude/settings.json` and commit it (as of November 2026). A hook that refuses to end a session with unpushed commits is a good first one. 11. **Schedule the sweeper.** Set it to run twice a day with a hard time cap on each run. Use cron, or the scheduler on my system. Ask before you create the schedule (asks before running). 12. **Approve the first live release.** Stop. Tell me what the deployer will publish, and wait for my yes before the first production release. Do this by hand, once. ## How to check it worked - Each agent file exists in `.claude/agents/`, and each lists only the tools it needs. - The queue view shows one build in flight at most, with blocked rows last. - The sweeper has run once, and its output file is fresh and has a date from today. - A test build reaches "live" only after a success response from its health address, and stays out of "shipped" until I mark it. - Name the small win: you now have a team with clear jobs. Then tell me the time I got back, and nudge me to spend it on someone or something I love. ## If something goes wrong - A sweeper run did not start. Check how fresh its output is, not the exit code. A job set for a time the computer was off may never have run. Ask me before changing the schedule. - A run ended at a login wall. Stop, tell me, and ask me to sign in to the official app myself. Never ask me for the login. - An agent is missing a tool it needs. Stop and tell me which tool and why. Put back only that tool. - A tunnel or service looks fixed after one good check. Run a second check after a delay before closing the ticket. - If you are stuck or unsure, stop. Do not retry the same step over and over. Use the official docs: https://code.claude.com/docs/en/sub-agents. ## Never do this - Never let an agent deploy, spend money or message customers without my approval. - Never leave an agent without a tools line. It may inherit every connected tool. - Never push a personal or financial repository. - Never paste a secret into this chat. - Never run a command you do not understand. Ask me to explain it first. - Never use an unofficial download, a cracked app, or a script from a forum. ## Sources 1. Anthropic (Claude Code Docs). "Create custom subagents." https://code.claude.com/docs/en/sub-agents. Checked November 12, 2026. 2. Anthropic (Claude Code Docs). "Hooks reference." https://code.claude.com/docs/en/hooks. Checked November 12, 2026. 3. Anthropic (Claude Code Docs). "Settings files and precedence." https://code.claude.com/docs/en/settings. Checked November 12, 2026. 4. GitHub CLI. "Manual." https://cli.github.com/manual/. Checked November 12, 2026. 5. GitHub CLI. "gh repo create." https://cli.github.com/manual/gh_repo_create. Checked November 12, 2026. ## About this file Made by technologytips.blog from the article https://technologytips.blog/articles/ai-coding-agent-team-build-deploy-fix/, checked against its sources on November 12, 2026. Written with AI, checked against the article and security-scanned. General help, not professional support. Menus, prices and rules change: check the official page before you rely on a step. Free to use and share with credit to technologytips.blog (CC BY 4.0).