You Lead, AI Assists.

BuildCrew is an installable plugin package containing a provider-neutral, evidence-driven AI software engineering skill for understanding projects, making focused changes, preserving context, and reporting what was actually verified.

Get started

BuildCrew works best when it can read the repository it is helping with. Open the project in your AI coding tool (host), make sure its existing instructions are available, and have a specific task or question ready.

1. Install BuildCrewChoose the supported plugin-package installation or a direct BuildCrew skill installation from the installation section below.
2. Start a new sessionNew sessions load newly installed skills and prevent stale instructions from an earlier conversation.
3. Begin with contextTell BuildCrew the goal, target area, constraints, and how success will be measured. Ask it to inspect before editing.
4. Review the planConfirm the scope and approach before asking BuildCrew to implement anything.
5. Verify the resultAsk for focused tests or checks, then review the evidence and remaining risk.

Your first prompt

CopyUse BuildCrew to inspect this repository and plan a small feature. Do not edit files yet.

Installation

BuildCrew is an installable plugin package containing a portable skill. Choose the installation method that matches your AI coding tool. Installation is inert until the host loads BuildCrew and runs the one-time activation and onboarding flow.

Step 1: Install BuildCrew in your AI coding tool

Download the plugin ZIP

Ready-to-paste ZIP installation prompt

Paste this prompt into the host where you want BuildCrew installed. Replace [ZIP_FILE_PATH] with the path to the ZIP you already downloaded. It requests a global installation and does not modify a project.

CopyI have already downloaded the BuildCrew ZIP file here:
[ZIP_FILE_PATH]

Install BuildCrew globally for this host, not for only one project. Use the local ZIP file above; do not download another copy.

Extract the ZIP into a temporary location and validate that the extracted buildcrew/ directory contains plugin.json, skills/, and hooks/. Install that extracted buildcrew/ plugin directory using this host's supported global plugin or local-marketplace installation method.

Do not copy files into the current project, do not install the ZIP as a skill directory, and preserve unrelated host settings. If the ZIP path is missing, invalid, or ambiguous, ask me for the exact path before changing anything.

Review the bundled hooks/hooks.json and UserPromptSubmit hook before enabling it. If this host cannot install a local ZIP/plugin globally, explain the exact limitation and give me the host-specific manual location instead of claiming success.

After installation, configure BuildCrew as the global engineering workflow for every input across every project in this host. Run the one-time global activation and keep its receipt outside project folders. Then tell me what was installed, where, whether the hook is trusted and active, and whether I should start a new session.

Do not modify project files. Do not claim that BuildCrew is persistent unless you can verify the global installation and activation.

Codex plugin

Copycodex plugin marketplace add idhavaltank/buildcrew
codex plugin add buildcrew@buildcrew

Restart Codex or start a new CLI thread. Then run the global setup prompt and verify activation in a fresh session.

Claude Code

From the BuildCrew repository root:

Copymkdir -p .claude/skills/buildcrew
cp -R SKILL.md config engine references schemas scripts .claude/skills/buildcrew/

For a global installation, use ~/.claude/skills/buildcrew/ instead of the project-local path.

Cursor, Windsurf, Cline, Kiro, Zed, and Copilot Chat

Copy the included AGENTS.md into the target project root when the host supports repository instructions. Otherwise, copy BuildCrew package contents (`SKILL.md`, `config/`, `engine/`, `references/`, `schemas/`, and `scripts/`) into the host’s native skill or rules directory.

Gemini CLI, Antigravity, OpenCode, and other hosts

Use the host’s native plugin or skill installer when available and provide the BuildCrew plugin package or skill directory. If the host supports neither the Agent Skills format nor AGENTS.md, it needs a small host-specific adapter. This repository currently provides the portable plugin package, its BuildCrew skill, and fallback instructions, not a native one-command installer for every host.

Windows PowerShell (Codex)

CopyNew-Item -ItemType Directory -Force "$HOME\.codex\skills\buildcrew"
Copy-Item "SKILL.md", "config", "engine", "references", "schemas", "scripts" "$HOME\.codex\skills\buildcrew" -Recurse -Force

Host runtime configuration for multi-agent execution

Live multi-agent execution requires an approved native-agent executor (the component that starts an agent), a model provider (the AI model service), a runtime coordinator (the component that manages agent assignments), a project scope, and execution permissions. Configure each AI coding tool separately; installing BuildCrew in one host does not configure it in another. BuildCrew never claims that agents ran unless the host returns valid execution evidence.

Step 2: Configure BuildCrew globally

After installation, send this advanced one-time setup prompt at the Codex level. It asks the host to load BuildCrew for every input across all projects, starts project onboarding when needed, and configures continuity where supported. This step is required for smooth continuous use of BuildCrew.

CopyI installed BuildCrew globally. Make BuildCrew the single engineering workflow for every input in every project in this Codex installation, including questions, follow-ups, reviews, plans, and coding tasks. Handle simple questions briefly.

First, locate and validate the installed SKILL.md. Check this tool's global Codex instructions and whether another engineering controller is active. Follow BuildCrew's activation checks and keep a reversible way to restore the prior configuration. Add the smallest supported global instruction or lifecycle hook to use BuildCrew on each input across every project. Preserve unrelated settings. If another controller already owns this scope, report the conflict before changing it.

Run BuildCrew's one-time global activation and keep its receipt in an approved directory outside all projects. Run per-project onboarding only when a repository is first opened. On every later input, invoke scripts/global_input_adapter.py with a sanitized intake: simple questions use lookup only, while actionable work starts or resumes its exact task. At completed, blocked, or paused closure, invoke scripts/context_loop.py close. Keep one shared BUILDCREW_HOME across projects and sessions.

Report what you configured, where, and the onboarding state. Tell me whether to reload or start a new session, and how to verify BuildCrew with an ordinary project request that does not name it. If this tool cannot make or verify BuildCrew persistent, say so.

Step 3: Start a fresh session and verify activation

Reload Codex or start a new session, open any repository, then send an ordinary request without naming BuildCrew:

CopyInspect this project and explain the relevant existing patterns before making any changes. Do not edit files yet.

Verify that the response follows the BuildCrew workflow and reports what it inspected. If the host cannot confirm persistent activation, use BuildCrew explicitly and follow the host-specific limitation it reports.

Core concepts

BuildCrew is an installable plugin package containing the BuildCrew skill, lifecycle workflow, and set of evidence-bound contracts—rules that connect decisions to verifiable evidence—working together.

BuildCrew operating modes

BuildCrew selects the appropriate mode based on the task’s complexity and risk. You can also request a specific mode when the task requires it.

Workflows

Choose the BuildCrew route that matches the work. Routine changes stay lightweight; coupled or risky changes receive stronger planning, evidence, and review.

Understand and plan

CopyUse BuildCrew to inspect the repository, retrieve relevant context, and produce a bounded implementation plan for adding an empty state to the profile screen. Do not edit files.

Implement

CopyUse BuildCrew to implement the approved plan. Reuse existing patterns, keep the change focused, and run the relevant checks.

Review and verify

CopyUse BuildCrew to review this diff for correctness, security, missing evidence, unnecessary complexity, and runtime limitations.

Complete and learn

At completed, blocked, or paused closure, record the evidence, residual risk, worklog, and sanitized learning outcome. Candidate knowledge requires separate review before canonical memory promotion.

Multi-agent engineering team

When the host runtime supports agent execution, BuildCrew can coordinate specialist agents for larger or higher-risk work. For example, a project architecture request may use the following sequence:

1. Understand the requestThe Orchestrator and Context Coordinator define the goal, scope, and acceptance criteria.
2. Research the projectThe Knowledge Retriever and Codebase Analyst inspect documentation, source, dependencies, and existing patterns.
3. Design the architectureThe Solution Architect turns the verified findings into a bounded architecture proposal.
4. Review and validateThe Independent Reviewer checks risks and gaps, then the Final Validator confirms the evidence.

These agents are selected according to the task. If the host cannot spawn agents, the lead AI follows the same workflow and reports the capability limitation honestly.

Examples

Adapt these patterns to your repository and constraints.

New project

Undocumented project

Learn from source, configuration, dependencies, and tests. Record the documentation gap, save reusable context through the controlled learning path, and avoid treating assumptions as facts.

Prompt and response reference

Make BuildCrew’s scope, route, acceptance criteria, and expected output explicit.

Reusable prompt

CopyUse BuildCrew.
Goal: [desired outcome]
Target: [project area]
Constraints: [important limits]
Acceptance criteria: [how success will be checked]
Do not [explicitly excluded work].

Completion response

1. Summary: what was requested and what was done.
2. Changed files: the files or areas that moved.
3. Verification: commands, tests, inspections, or previews that actually ran.
4. Not checked: relevant checks that did not run.
5. Risk: assumptions, runtime limitations, or follow-up validation.

FAQ

Is BuildCrew a plugin or a skill?

BuildCrew is an installable plugin package that contains the BuildCrew skill. The plugin handles distribution and metadata; the skill contains the provider-neutral engineering workflow.

Does BuildCrew write code automatically?

Only when the host routes an actionable request and you authorize the work. The recommended workflow begins with onboarding or context lookup, current-source inspection, and a bounded plan.

Does BuildCrew guarantee correct code?

No. It improves understanding, implementation, memory continuity, and verification. It cannot prove production, browser, device, or provider behavior that was not exercised.

Does installation activate BuildCrew automatically?

Installation is inert. Persistent every-input use requires the host's supported global instruction, lifecycle hook, or equivalent loading mechanism. Global activation is configured once per installation and host; project onboarding prevents the introduction from repeating for each repository.

Does BuildCrew spawn agents automatically?

BuildCrew selects the required roles automatically only when the host runtime supports agent execution. Without that configuration, the lead AI follows the same workflow and reports that separate agent execution is unavailable.

What is a host?

A host is the AI coding tool that loads and runs BuildCrew, such as Codex, Claude Code, Cursor, Windsurf, or Gemini CLI. Each host must be configured separately for live multi-agent execution.

What happens when agent execution is unavailable?

BuildCrew continues with the lead AI. It can still inspect the project, plan changes, implement approved work, run available checks, and report evidence without pretending that separate agents ran.

How does BuildCrew handle memory?

Every input may perform a bounded local lookup. Actionable work can start or resume an exact task. At closure, BuildCrew stores only sanitized, scoped, evidence-backed learning; current source still outranks memory.

Contributing

BuildCrew is an open-source plugin package developed and maintained by Dhaval Tank for the community. Anyone can use the plugin package, create their own versions, and contribute improvements through pull requests. Dhaval Tank maintains the official plugin package and its BuildCrew skill, and reviews all contributions to ensure quality, consistency, and reliability before approving them for inclusion in the official version.

1. Open an issue firstDescribe the problem, host, expected behavior, and smallest useful improvement.
2. Fork and create a branchKeep one focused change per pull request.
3. Verify the changeCheck links, manifests, installation examples, and Pages rendering.
4. Open a pull requestExplain what changed, why, how it was tested, and what remains uncertain.
5. Wait for maintainer reviewThe maintainer will review your contribution. Once approved, it will be accepted and merged into the protected main branch.