BuildCrew #

The Build Crew for AI Development

A collection of custom AI agents, skills, and commands for software development teams. Installable across multiple AI coding platforms including OpenCode, Claude, and GitHub Copilot.

What is BuildCrew? #

BuildCrew provides role-based development agents and technology-specific skills that enhance AI-assisted coding workflows:

• Agents - Specialized AI personas that complement, rather than override, platform defaults
• Skills - Technology and framework-specific knowledge packs
• Commands - Reusable prompt templates for common development tasks

Supported harnesses:

• pi
• GitHub Copilot CLI
• Claude Code
• OpenCode

How BuildCrew Works #

BuildCrew is designed around a small set of roles that match the way software work usually moves from idea to implementation to release.

Agent behavior in the workflow #

Each role has a specific job in the lifecycle:

Role	Behavior
Architect	Designs the blueprint before implementation. It inspects context, challenges incomplete assumptions, compares realistic options, chooses a pragmatic direction, defines boundaries, plans verification, and creates a developer handoff. It does not write implementation code.
Developer	Implements the requested change with readable, maintainable code. It follows a TDD-first workflow when practical, reuses existing utilities and patterns before adding new logic, keeps changes small and reviewable, watches for security and performance pitfalls, and verifies the result with focused tests.
Tester	Complements the Developer by finding test gaps. It generates missing tests, analyzes meaningful coverage, debugs failing tests, recommends test strategy, and focuses on edge cases, error paths, and conventions. It edits only test files, fixtures, or test helpers.
Reviewer	Critiques code without modifying files. It reviews correctness, test quality, security, performance, maintainability, dependency risk, and refactoring opportunities, then produces actionable findings and a developer handoff when fixes are needed.
Prepare Commit	Turns finished work into commit and PR text. It adapts to the repo state, summarizes the change, and asks before committing, pushing, or opening a PR.

Architecture-first flow #

Use this for larger features, migrations, risky changes, or work where the structure is not obvious yet.

  +-----------+      +-----------+      +------+      +--------+      +------------------+
  | Architect | ---> | Developer | ---> | Test | ---> | Review | ---> | Prepare Commit  |
  +-----------+      +-----------+      +------+      +--------+      +------------------+
        |                  ^              |              |
        |                  |              v              v
        +---- handoff -----+        fix gaps/failures   fix review findings

Typical flow:

architect -> developer -> test -> review -> prepare-commit

How the roles interact:

1. Architect clarifies scope, challenges assumptions, compares trade-offs, and produces a concrete implementation handoff.
2. Developer implements the handoff or request, adding or updating tests before code when practical.
3. Tester checks for missing coverage, weak assertions, failing tests, and important edge cases.
4. Reviewer audits the change for correctness, maintainability, security, performance, and dependency risks.
5. Prepare Commit prepares commit and PR text once the work is ready.

Example prompts, using generic role names:

Architect: Design a user authentication system
Developer: Implement the authentication module with tests
Test: Check for test gaps in the authentication changes
Review: Review the authentication changes
Prepare Commit: Prepare commit and PR text

Fast implementation flow #

Use this for small fixes, straightforward features, or work that already has a clear design.

  +-----------+      +------+      +--------+      +------------------+
  | Developer | ---> | Test | ---> | Review | ---> | Prepare Commit  |
  +-----------+      +------+      +--------+      +------------------+
        ^              |              |
        |              v              v
        +-------- fix gaps/failures / review findings

Typical flow:

developer -> test -> review -> prepare-commit

Skip the Architect when the implementation path is already clear. The Developer still follows the same quality bar: inspect existing patterns, prefer TDD, keep the change focused, and verify behavior before moving to test and review.

Example prompts, using generic role names:

Developer: Fix the failing validation test
Test: Check the updated tests
Review: Review the current diff
Prepare Commit: Prepare commit and PR text

Each harness invokes these roles differently. Use the section for your tool below.

Install & Use by Harness #

pi #

BuildCrew ships as a native pi package. The package includes:

• A pi extension (pi/extensions/buildcrew-pi.ts) that registers slash commands and agent personas.
• Shared skills under skills/, discovered automatically by pi.

Install #

# User-level config (default)
pi install npm:@hjkl.io/buildcrew

# Project-level config
pi install -l npm:@hjkl.io/buildcrew

Note: pi install only configures pi. It does not install recipes into OpenCode, Claude, or Copilot. Use npx @hjkl.io/buildcrew install <platform> for those platforms.

Use #

/architect Design the authentication module
/developer Implement the authentication module
/test Check for test gaps
/review Review the current diff
/prepare-commit Prepare commit and PR text

Run /buildcrew to see available commands and the active agent.

How pi personas work #

pi does not have the same @agent and subagent model as OpenCode. BuildCrew emulates it with two mechanisms:

1. Sticky personas — /architect and /developer inject their system prompt on every turn until you switch to another sticky agent or run /buildcrew-reset.
2. One-shot personas and commands — /reviewer, /tester, /review, /refactor, /test, and /prepare-commit apply only to the next turn.

Command	Mode	Description
/architect <prompt>	sticky	Activate the Architect persona
/developer <prompt>	sticky	Activate the Developer persona
/reviewer <prompt>	one-shot	Invoke the Reviewer persona once
/tester <prompt>	one-shot	Invoke the Tester persona once
/review [scope]	one-shot	Review current uncommitted changes
/refactor <path>	one-shot	Behavior-preserving refactor
/test [subcommand]	one-shot	Test analysis, generation, or debugging
/prepare-commit	one-shot	Prepare commit message and PR text
/buildcrew	—	Show active agent and available commands
/buildcrew-reset	—	Clear the active sticky agent

/architect and /developer are sticky personas. After /developer is active, follow-up prompts continue as Developer until you switch agents or run /buildcrew-reset. In pi, the latest marked Architect handoff is automatically injected into the first Developer turn; no separate handoff command is required.

Because pi has no built-in per-agent permissions, the extension enforces read-only rules at the tool level:

• Architect and Reviewer cannot run edit, write, or destructive bash commands (rm, git commit, git push, >, sudo, etc.).
• Tester can only edit files inside test paths (tests/, __tests__/, spec/, or files ending in .test.*, .spec.*, _test.go, test_*).
• Developer has no additional restrictions beyond pi's defaults.

To try the extension without installing the package:

pi -e ./pi/extensions/buildcrew-pi.ts

Installed files #

pi installs BuildCrew as a package and loads the extension and skills from the package itself.

• Extension: pi/extensions/buildcrew-pi.ts
• Skills: skills/*

GitHub Copilot CLI #

Install #

No clone is required. Install directly with npx:

# Project-level install
npx @hjkl.io/buildcrew install copilot

# User-level install
npx @hjkl.io/buildcrew install copilot -u

For frequent use, you can install the CLI globally:

npm install -g @hjkl.io/buildcrew
buildcrew install copilot -u

Use #

Copilot CLI uses its own custom-agent picker. It does not invoke custom agents with @architect, @developer, or /architect.

In an interactive Copilot CLI session, use:

/agent

Then select architect, developer, reviewer, or tester.

For non-interactive use, pass the agent explicitly:

copilot --agent architect --prompt "Design the authentication module"
copilot --agent developer --prompt "Implement the authentication module"

BuildCrew commands are installed so you can use slash-style prompts where Copilot exposes skills:

/review
/test
/prepare-commit

At user level, commands are installed as skills into ~/.copilot/skills/ alongside regular skills. If a skill and command share the same name, the last one installed wins. BuildCrew avoids this by convention: skill names and command names in the manifest are distinct.

Installed files #

Project install (default):

• .github/agents/*.agent.md (agent profiles with Copilot CLI frontmatter)
• .github/skills/*/SKILL.md
• .github/prompts/*.prompt.md

User install (-u):

• ~/.copilot/agents/*.agent.md
• ~/.copilot/skills/<skill>/SKILL.md (skills)
• ~/.copilot/skills/<command>/SKILL.md (commands installed as skills for slash-command access)

Agent file transformation: Copilot CLI requires .agent.md files with name and description frontmatter. BuildCrew automatically transforms agent files from the platform-agnostic source format into Copilot's format during install.

Claude Code #

Install #

# Project-level install
npx @hjkl.io/buildcrew install claude

# User-level install
npx @hjkl.io/buildcrew install claude -u

For frequent use, you can install the CLI globally:

npm install -g @hjkl.io/buildcrew
buildcrew install claude -u

Use #

Use Claude's agent and skill UI for installed BuildCrew agents and commands. If your Claude Code version exposes installed agents directly, choose architect, developer, reviewer, or tester from that UI. You can also ask for the role in plain language:

Use the architect agent to design the authentication module.
Use the developer agent to implement the authentication module.

BuildCrew installs commands as skills for Claude Code, so command-style workflows are available through Claude's skills system:

/review
/test
/prepare-commit

Claude Code requires agent files with name and description frontmatter. BuildCrew automatically transforms agent files from the platform-agnostic source format into Claude-compatible format during install.

Installed files #

Project install (default):

• .claude/agents/*.md (agent profiles with frontmatter)
• .claude/skills/*/SKILL.md

User install (-u):

• ~/.claude/agents/*.md
• ~/.claude/skills/*/SKILL.md

Agent file transformation: Claude Code requires agent files with name and description frontmatter. BuildCrew automatically transforms agent files from the platform-agnostic source format into Claude-compatible format during install.

Commands merged into skills: Claude Code has merged custom commands into the skills system. BuildCrew installs commands as skills so they are available as slash commands (/review, /test, etc.).

OpenCode #

Install #

# Project-level install
npx @hjkl.io/buildcrew install opencode

# User-level install
npx @hjkl.io/buildcrew install opencode -u

For frequent use, you can install the CLI globally:

npm install -g @hjkl.io/buildcrew
buildcrew install opencode -u

Use #

OpenCode supports direct @agent invocation:

@architect Design the authentication module
@developer Implement the authentication module
@tester Check for test gaps
@reviewer Review the current diff

BuildCrew commands are available as slash commands:

/review
/test
/refactor
/prepare-commit

@architect and @developer are the main entry points. @reviewer and @tester are useful for deeper audits, test-gap analysis, and parallel subagent work.

Installed files #

Project install (default):

• .opencode/agents/*.md
• .opencode/skills/*/*.md
• .opencode/commands/*.md

User install (-u):

• ~/.config/opencode/agents/*.md
• ~/.config/opencode/skills/*/*.md
• ~/.config/opencode/commands/*.md

CLI Reference #

Use the BuildCrew CLI to install, inspect, and remove recipes for GitHub Copilot CLI, Claude Code, and OpenCode.

install <platform> #

Install or update BuildCrew recipes for a platform.

# Install into current project (default)
buildcrew install copilot
buildcrew install claude
buildcrew install opencode

# Install into a specific project directory
buildcrew install copilot -t ./my-project

# Install into user-level config
buildcrew install copilot -u
buildcrew install claude -u
buildcrew install opencode -u

# Preview changes without applying
buildcrew install copilot --dry-run

# Force overwrite conflicting files
buildcrew install copilot --force

Use -u to install into user-level config:

• opencode: ~/.config/opencode/
• claude: ~/.claude/
• copilot: ~/.copilot/

On NixOS or other declarative systems, npm install -g may not work because global directories are read-only. Use npx instead:

npx @hjkl.io/buildcrew install copilot
npx @hjkl.io/buildcrew install opencode -u

Alternatively, install locally in your project:

npm install -D @hjkl.io/buildcrew
npx buildcrew install copilot

uninstall <platform> #

Remove BuildCrew recipes for a platform.

buildcrew uninstall copilot
buildcrew uninstall claude -t ./my-project

doctor <platform> #

Check the status of installed recipes.

buildcrew doctor copilot
buildcrew doctor opencode -u

list #

List available platforms or recipes.

buildcrew list platforms
buildcrew list

Agents #

Architect #

The Architect agent designs system architecture, makes technology decisions, and creates architecture-first technical feature plans. It focuses on structure over code, with explicit support for parallel agent execution.

Developer #

The Developer agent implements requested functionality with a TDD-first workflow. It focuses on readable, maintainable, well-tested code for human reviewers, reuses existing functionality before adding custom logic, keeps functions and files small, avoids dead code and unused imports, watches for common security pitfalls, and never creates commits unless explicitly asked.

Reviewer #

The Reviewer agent critiques code, identifies risks, and suggests improvements for both current changes and existing codebase areas. It reviews for correctness, test coverage, security, performance, maintainability, dependency risk, and refactoring opportunities. It does not modify files directly; instead, it produces actionable findings with a Developer Handoff section for implementation.

Tester #

The Tester agent ensures code quality through test generation, coverage analysis, and debugging. It does not replace the Developer's TDD workflow — it complements it by filling gaps the developer may miss.

Use the Tester when:

• Adding tests to existing code that lacks coverage
• Debugging mysteriously failing tests
• Checking test coverage before opening a PR
• Planning test strategy for complex features

Tester modes:

• @tester (default) — Analyze current test state and report gaps
• @tester generate <path> — Generate tests for source files
• @tester coverage — Detailed coverage gap analysis
• @tester debug — Debug failing tests and suggest fixes
• @tester strategy <feature> — Recommend test approach before implementation

The Tester never modifies production source code — only creates or edits test files.

Agent modes #

BuildCrew agents use OpenCode's mode option to describe primary agents and subagents. The field is preserved when installing to Claude Code and GitHub Copilot so the same intent remains in the installed files, even though those platforms may expose agents through different UI.

• Primary entry points (architect, developer) are the usual starting points.
  • architect uses mode: primary.
  • developer uses mode: all so it can also be spawned as a subagent for parallel implementation tracks.
• Subagents (reviewer, tester) are designed for review, test-gap analysis, and other focused work. They use mode: subagent.

In OpenCode these names are commonly invoked as @architect, @developer, @reviewer, and @tester. In other harnesses, use the invocation style documented in that harness section.

BuildCrew intentionally does not provide build or plan agents. Those names are reserved by some platforms for their default agents, and BuildCrew avoids changing default platform behavior. New agents should use distinct names that describe their specific role.

Command Reference #

Command invocation depends on the harness, but the intent is consistent across platforms.

/review #

Use /review for a focused review of current changes.

• Reviews the current diff or staged changes
• Looks for correctness, test coverage, maintainability, security, and performance issues
• Delegates to the Reviewer persona where the harness supports that behavior

/test #

Use /test before submitting code or when you want test-specific feedback.

• Checks for coverage gaps in your changes
• Helps diagnose failing tests
• Can guide test generation depending on the harness and prompt
• Complements the Developer's TDD workflow rather than replacing it

This is especially valuable when:

• You did not follow strict TDD
• You are touching complex or critical logic
• You want confidence in test coverage before opening a PR

/refactor #

Use /refactor for behavior-preserving cleanup.

• No behavior changes
• No new features
• Tests should already exist or be added first
• Best for reducing complexity, improving naming, or simplifying structure

/prepare-commit #

Use /prepare-commit when you are ready to commit or open a PR.

• Prepares commit message, PR title, and PR description
• Adapts to repo state: uncommitted changes or committed diff
• Only prepares text by default
• Asks before committing, pushing, or opening a PR
• Uses gh for PR creation if available; otherwise provides copy-paste text

Customizing Agents #

To customize an agent for your project:

1. Install BuildCrew for your platform
2. Edit the installed files directly (they are marked with BuildCrew comments)
3. Or fork this repo, modify agents/, and publish your own package

Development #

Repository Structure #

buildcrew/
├── agents/          # Role-based AI agents
│   ├── architect.md
│   ├── developer.md
│   ├── reviewer.md
│   └── tester.md
├── skills/          # Technology-specific skills
│   ├── react/
│   ├── kubernetes/
│   └── _template/
├── commands/        # Reusable command prompts
│   ├── review.md
│   ├── refactor.md
│   ├── prepare-commit.md
│   └── test.md
├── src/             # CLI source code
│   ├── cli.js
│   ├── commands/
│   ├── platforms/
│   └── utils/
├── pi/              # pi extension and config
│   └── extensions/
│       └── buildcrew-pi.ts
├── bin/             # CLI entry point
│   └── buildcrew.js
├── manifest.json    # Package manifest
└── package.json

Running Tests #

BuildCrew uses Node.js built-in test runner (no external test dependencies):

npm test

This runs all platform adapter tests to verify correct install paths for project and user scopes, plus the pi extension recipe loading tests.

Testing the pi extension #

Load the extension directly without publishing:

pi -e ./pi/extensions/buildcrew-pi.ts

Inside pi, run:

/buildcrew
/architect hello

Testing Changes #

Before submitting changes, verify install paths work correctly:

# Test project install
node bin/buildcrew.js install opencode --dry-run
node bin/buildcrew.js install claude --dry-run
node bin/buildcrew.js install copilot --dry-run

# Test user install
node bin/buildcrew.js install opencode -u --dry-run
node bin/buildcrew.js install claude -u --dry-run
node bin/buildcrew.js install copilot -u --dry-run

Contributing #

Contributions are welcome! Here's how to get started:

1. Add new agents to agents/ following the template in agents/_template.md
2. Add skills to skills/<name>/SKILL.md
3. Update manifest.json if adding new file types
4. Test your changes with node bin/buildcrew.js install <platform> --dry-run
5. Test the pi extension with pi -e ./pi/extensions/buildcrew-pi.ts
6. Run tests with npm test to verify platform adapters and pi recipe loading
7. Submit a pull request on tangled.org

Development Setup #

git clone https://tangled.org/hjkl.io/buildcrew
cd buildcrew
npm install
npm test

License #

MIT License - see LICENSE file for details.