Get Started

Set up Blackbox for your role in a few simple steps.

Requirements

Before you start, make sure you have these set up.

Claude Code

Anthropic's CLI for Claude. This is what runs the skills.

Asana

Project management where tickets live. All roles collaborate here.

Asana MCP Server

Connects Claude Code to Asana. Lets skills read and write tickets directly.

Quick Start for Developers

Clone the Repository

This gives you the skills and templates.

git clone https://github.com/elvisnm/blackbox.git

Initialize Project

Install Blackbox into your project. This creates the .blackbox/ folder and loads all skills into .claude/commands/.

bbox init /path/to/your-project

Set Asana Token

Required for /scaffold, /refresh, /send-back, and all ticket management skills.

In Asana, go to My Settings → Apps → Developer Apps
Under Personal Access Tokens, click Create New Token
Give it a name (e.g., "Blackbox") and copy the generated token

# Save your Asana token to bbox config bbox set asana-token your-token

Verify Your Setup

Run the health check to confirm everything is configured correctly.

bbox check

Add Repo (Optional)

Links your repository to the dashboard. This is auto-detected during initialization if a git remote exists.

bbox add-repo owner/repo --branch main

The .blackbox/ Folder

project-structure

your-project/
└── .blackbox/
    ├── blueprints/
    │   ├── _template.md
    │   ├── feat/
    │   ├── fix/
    │   ├── improve/
    │   └── hotfix/
    └── prs/
        ├── _template.md
        ├── feat/
        ├── fix/
        ├── improve/
        ├── hotfix/
        └── reviews/

feat/

New functionality and features.

fix/

Bug fixes and error resolutions.

improve/

Refactors and performance.

hotfix/

Urgent production fixes.

Blueprint Anatomy

Asana-Owned

Generated instantly when running /scaffold.

Goal
Context
Requirements
UI / UX
Constraints

Developer-Owned

Fleshed out locally via /refine and during implementation.

Codebase Context
Implementation Plan
Technical Decisions
Validation

Blueprints carry only two links: the Asana ticket URL and the PR link. No status, no changelog — Asana handles all workflow tracking.

Setup by Role

DEV: Generate Role Configs (one-time setup)

After running bbox init, the developer generates personalized CLAUDE.md files for PO and DESIGN roles. These are committed to the repo so every team member gets the same configuration.

in Claude Code

# Run the setup-roles skill in Claude Code /setup-roles

# This generates two files: .blackbox/roles/CLAUDE_PO.md .blackbox/roles/CLAUDE_DESIGN.md

# Review, then commit git add .blackbox/roles/ && git commit -m "add PO and DESIGN role configs" && git push

The skill spawns agents that read your codebase and generate role-specific configs with actual file paths, feature descriptions, and project context. No manual template editing needed.

Product Owner (PO)

Clone the project into a separate folder

git clone <repo-url> my-project-po

Copy the PO config as your CLAUDE.md

cp .blackbox/roles/CLAUDE_PO.md CLAUDE.md

Set your Asana token

bbox set asana-token your-token

Open in Claude Code

Open the folder in the Claude app or run claude from the terminal. You're ready to use /draft, /refine, and /review-ticket.

Key Point: PO's Claude reads the codebase for context but writes only to Asana. Never touches the repo.

Designer

Clone the project into a separate folder

git clone <repo-url> my-project-design

Copy the DESIGN config as your CLAUDE.md

cp .blackbox/roles/CLAUDE_DESIGN.md CLAUDE.md

Set your Asana token

bbox set asana-token your-token

Open in Claude Code

Open the folder in the Claude app or run claude from the terminal. You're ready to use /design and /review-design.

Key Point: Designer's Claude researches existing UI patterns and references components by name. Writes only to Asana.

QA

No Claude setup needed. QA works directly in Asana, testing against the acceptance criteria in the ticket.

Dashboard Setup (Optional)

The dashboard reads blueprint data from GitHub, not your local filesystem. Your project's .blackbox/ directory must be committed and pushed to GitHub for the dashboard to display it. Private repos require a GitHub token.

How to get a GitHub token:

Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
Click Generate new token (classic)
Name it (e.g., "Blackbox Dashboard") and select the repo scope for private repos
Click Generate token and copy it (starts with ghp_)

dashboard-init

# 1. Install dependencies cd blackbox/dashboard && npm install

# 2. Make sure .blackbox/ is committed and pushed to GitHub git add .blackbox/ && git commit -m "add blackbox blueprints" && git push

# 3. Add repos to track bbox add-repo owner/repo --branch main

# 4. Add GitHub token (required for private repos, optional for public) bbox set token ghp_your-token

# 5. Run dashboard npm run dev → opens at localhost:5173

# 6. Verify setup bbox check