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.

Project Management Tool

e.g. Asana, Jira, Trello, Linear, GitHub Issues, Notion, ClickUp, or Shortcut.

Provider Token

An API token for your project management tool. Lets skills read and write tickets directly.

Blackbox is licensed under the Blackbox License v1.0. Check the license page for the full details.

Quick Start for Developers

1

Clone the Repository

This gives you the skills and templates.

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

Initialize Project

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

bbox init /path/to/your-project
3

Set Provider

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

  1. Choose your project management tool: asana, github, linear, jira, notion, trello, clickup, or shortcut
  2. Get an API token from your tool's settings
  3. Configure both with the commands below
# Set your project management tool and token bbox set provider asana
bbox set provider-token your-token
4

Verify Your Setup

Run the health check to confirm everything is configured correctly.

bbox check
5

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

Ticket-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 ticket URL and the PR link. No status, no changelog — your project management tool 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)

1

Clone the project into a separate folder

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

Copy the PO config as your CLAUDE.md

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

Set your provider token

bbox set provider-token your-token
4

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 the project management tool. Never touches the repo.

Designer

1

Clone the project into a separate folder

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

Copy the DESIGN config as your CLAUDE.md

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

Set your provider token

bbox set provider-token your-token
4

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 the PM tool.

QA

No Claude setup needed. QA works directly in the project management tool, 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:

  1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Click Generate new token (classic)
  3. Name it (e.g., "Blackbox Dashboard") and select the repo scope for private repos
  4. 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