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.

Overview

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

Quick Start

No need to clone this repository. Install directly with npx:

# Install BuildCrew recipes into your current project
npx @hjkl.io/buildcrew install copilot
npx @hjkl.io/buildcrew install claude
npx @hjkl.io/buildcrew install opencode

# Or install into user-level config
npx @hjkl.io/buildcrew install opencode -u
npx @hjkl.io/buildcrew install claude -u
npx @hjkl.io/buildcrew install copilot -u

Supported platforms: opencode, claude, copilot

pi

For pi, install as a pi package:

# 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.

Then use BuildCrew agents and commands directly inside pi:

/architect Design the authentication module
/developer Implement the authentication module
/review
/test
/prepare-commit

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

CLI Installation

For frequent use, install the CLI globally:

npm install -g @hjkl.io/buildcrew

# Then use it directly
buildcrew install copilot
buildcrew install opencode -u

NixOS and Declarative Environments

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

# This works on NixOS, macOS, Linux, and Windows
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

Commands

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 opencode -u
buildcrew install claude -u
buildcrew install copilot -u

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

# Force overwrite conflicting files
buildcrew install copilot --force

Note: Use -u for opencode, claude, and copilot to install into user-level config.

• opencode: ~/.config/opencode/
• claude: ~/.claude/
• copilot: ~/.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

pi Support

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.

How it works

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.

pi Commands

Permission gates

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.

Example pi workflows

For small or obvious changes, start directly with the Developer agent:

/developer Fix the failing validation test
/test Check the updated tests
/prepare-commit Prepare commit and PR text

For larger changes, start with Architect and then hand off to Developer:

/architect Design a user authentication system
/developer Build it with tests
fix the edge case in token refresh
/test Check for test gaps in the authentication changes
/review Review the authentication changes
/prepare-commit Prepare commit and PR for the authentication changes

/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.

To try the extension without installing the package:

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

Platform Outputs

OpenCode

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

Claude

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.).

GitHub Copilot

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.md
• ~/.copilot/skills/*/SKILL.md (commands installed as skills for slash-command access)

⚠️ User-level namespace collision: At user level, commands are installed as skills into ~/.copilot/skills/ alongside regular skills. If a skill and command share the same name (e.g., a skill named test and a command named test), the last one installed wins. BuildCrew avoids this by convention — skill names and command names in the manifest are distinct.

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.

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

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 control how they are invoked. The mode field is preserved when installing to Claude Code and GitHub Copilot so the same primary/subagent semantics carry across platforms, even though those platforms may ignore the value today.

• Tab-selectable entry points (@architect, @developer) are selectable via the Tab key and act as main starting points.
  • @architect uses mode: primary.
  • @developer uses mode: all so it can also be spawned as a subagent for parallel implementation tracks (for example, when @architect splits work into independent tasks).
• Subagents (@reviewer, @tester) are designed to be spawned by primary agents via the Task tool or invoked manually with @. They use mode: subagent and are ideal for parallel work such as reviews and test-gap analysis.

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.

Workflow

BuildCrew agents and commands are designed to work together:

1. Design First

Start with @architect when planning new features or system changes.

• Designs architecture and technical plans
• Returns plans in conversation (does not modify files)
• Hands implementation tasks to @developer when ready

2. Implement

Use @developer for all implementation work.

• New features, bug fixes, refactoring, performance improvements
• TDD-first workflow
• Never commits unless explicitly asked

3. Review Current Changes

Use /review for quick review of uncommitted work.

• Focused on current diff/staged changes
• Delegates to @reviewer when available

4. Broader Audits

Use @reviewer for deeper analysis.

• Codebase audits, refactoring suggestions
• Security, performance, dependency reviews
• Read-only — does not modify files
• Best invoked as a subagent in parallel with other work

5. Refactor Safely

Use /refactor for behavior-preserving improvements.

• Uses @developer with strict constraints
• No behavior changes, no new features
• Tests must pass (write them first if missing)

6. Prepare Commit / PR

Use /prepare-commit when 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 PR
• Uses gh for PR creation if available; otherwise provides copy-paste text

7. Validate Tests Before PR

Use @tester before submitting code to ensure quality.

• @tester — Check for coverage gaps in your changes
• @tester debug — If any tests are failing, diagnose root cause
• /test — Quick test health check (same as @tester)
• Best invoked as a subagent in parallel with a final review

This is especially valuable when:

• You didn't follow strict TDD
• You're touching complex or critical logic
• You're submitting a PR and want confidence in test coverage

Example Flow

@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
@reviewer Audit the authentication module for security risks
/refactor Clean up the authentication service while preserving behavior
@tester debug Debug any failing tests from the refactor
/prepare-commit Prepare commit and PR for the authentication changes

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

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.