The Workflow

How work flows from idea to shipped code across two worlds.

Project Management

Where Product Owner, Designer, and QA live (e.g. Asana, Jira, Trello). Tracks status, assignments, and notifications. This is the shared space everyone sees.

Product Owner creates structured tickets with Claude
Designer enriches tickets with UI/UX specs and mockups
QA tests against the acceptance criteria in the ticket

Repository World

Where the Developer lives. Blueprints, code, and PRs. The technical recipe lives here, right next to the source code.

/scaffold Generate blueprint from ticket

/refine Agent Deep codebase research with parallel agents

/implement Execute the implementation plan

The Bridge

The ticket template is the bridge. It's a structured contract — the PO's Claude fills it, the Developer's Claude consumes it. When a ticket reaches Ready for Development, the developer runs /scaffold and the bridge is crossed.

Product Manager Tool World

e.g. Asana, Jira, Linear, Trello

Product Owner

Create Ticket

/draftCreate a new ticket using the contract template. Claude structures the goal, context, and requirements from the PO's input.

Refine

/refineDeep codebase research. Spawns 3 parallel agents to map affected areas, find patterns, and detect gaps. Then drives a guided Q&A before updating the ticket.

Review & Route

/review-ticketValidate ticket against quality gates. Checks for completeness, testable requirements, and empty Open Questions before routing to Design or Development.

Claude enforces ticket template

Designer optional

Add UI/UX

/designFill the UI/UX section of a ticket with component references from the codebase. Maps existing patterns and components to the new requirements.

Hand Off

/review-designValidate design specs against existing components and patterns. Flags inconsistencies or missing references before handing off to Development.

Mockups attached to ticket

Test

QA tests the feature against the acceptance criteria defined in the ticket. No Claude setup needed — works directly in the project management tool.

Approve

If all acceptance criteria pass, QA marks the ticket as Done. If issues are found, it's sent back to DEV as "PR Changes".

The Bridge

/scaffoldThe ticket template is the contract between Product Manager Tool and Repo worlds. When a ticket reaches "Ready for Development", the developer runs /scaffold and the structured content crosses into a blueprint.

Needs Refinement

/send-back → PODEV sends ticket back when requirements are wrong or incomplete. PO refines in the PM tool, then DEV runs /refresh to pull updates.

Ready for Development

When a ticket passes review and is marked "Ready for Development", the developer runs /scaffold to generate a blueprint from the ticket's structured content.

Needs Redesign

/send-back → DESIGNDEV sends ticket back when the UI spec doesn't work in practice. Designer reworks in the PM tool, then DEV runs /refresh.

PR Changes

QA found issues during testing. Ticket goes back to DEV with specific feedback. DEV fixes and re-submits for review.

Ready to Test

After the PR is created, the ticket moves to "Ready to Test". QA picks it up in the PM tool and tests against the acceptance criteria.

Done

Repository World

GitHub + Claude Code

Developer

Scaffold

/scaffoldGenerate a blueprint from a ticket. Pulls the structured content (Goal, Context, Requirements, UI/UX, Constraints) and creates the technical recipe in .blackbox/blueprints/.

Refine Agent

/refineSpawns 3 parallel research agents to map affected files, find existing patterns, and detect gaps. Then drives a guided Q&A to fill technical context and implementation plan.

Start

/startReview the blueprint summary — goal, progress counts, commit convention — and prepare to begin implementation.

Implement

/implementExecute the implementation plan step by step with task tracking. Each phase is worked through sequentially, checking off tasks as they're completed.

Review

/review-codeSelf-review changed files against a quality checklist before committing. Catches issues before they reach PR review.

Wrap Up

/wrap-upClean code, remove inline comments, run linters, generate a commit message, and create a PR document in .blackbox/prs/.

Create PR or Update PR GitHub PR

/create-prCreate a GitHub Pull Request from the PR document. Links back to the blueprint for full traceability.

Product Owner

Create Ticket

Refine

Review & Route

The Bridge

Designer optional

Add UI/UX

Hand Off

Developer

Scaffold

Refine

Start

Implement

Review

Wrap Up

Create PR

Test

Approve

Done

Two Sources of Truth

Product Manager Tool

Workflow status, assignments, notifications. What needs to happen and who's doing it.

Blueprint

Technical recipe. What to build, where in the code, how to verify. Lives in .blackbox/blueprints/

The ticket template is the CONTRACT between both sides.

Ticket Lifecycle

Every ticket in your project management tool moves through a sequence of statuses. Each status represents a clear handoff — when a ticket changes status, a different role picks it up. No one has to ask "is this ready?" or "whose turn is it?" The status tells you.

All Statuses

Draft

Refining

Ready for Design

Designing

Ready for Dev

In Progress

PR Review

Ready to Test

Testing

Done

Not every ticket takes the same path

Path	When	Skips
Standard	Features with UI changes	All steps
Fast Track	Backend, bugs, no UI	Design
Hotfix	Production is broken	Refine Design

Send-backs

Work can flow backward when requirements are wrong or issues are discovered.

DEV PO

Requirements wrong or incomplete

Status: Needs Refinement Command: /send-back

DEV DESIGN

UI spec doesn't work

Status: Needs Redesign Command: /send-back

DESIGN PO

Requirements unclear for UI mapping

Status: Needs Refinement

QA DEV

Issues found during testing

Status: PR Changes

After a send-back is resolved, the developer runs /refresh to pull the updated content into the existing blueprint. Ticket-owned sections are overwritten, developer-owned sections are preserved.

Developer Sequence

The full command flow from ticket to GitHub Pull Request.

/setup-roles Agent

Generate personalized CLAUDE.md files for PO and DESIGN roles. Run once after project setup.

/scaffold

Generate a blueprint from a ticket.

/refine Agent

Spawns parallel agents to research the codebase, then drives a guided Q&A to fill technical context and implementation plan.

/start

Review the blueprint summary and begin work.

/implement

Execute the implementation plan step by step with task tracking.

/review-code

Self-review changed files against a quality checklist.

/wrap-up

Clean code, run lint, and create a PR document.

/create-pr

Create a GitHub pull request from the PR document.

Everyone Moves Forward

The workflow isn't about adding process — it's about removing confusion. Each role knows exactly when their work starts, what they need to deliver, and when they're done. Send-backs catch problems early. Skills automate the handoffs. Nothing falls through the cracks.

Product Owner
defines

the what and why

Designer
shapes

the how it looks

Developer
builds

with full context