The Workflow

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

How It Works

The ticket template is the bridge. It is a structured contract: the Product Owner's Claude fills it, the Developer's Claude builds from it. When the ticket is complete, the developer runs /scaffold and the bridge is crossed. From that point, the workflow is not about adding process. It is about removing confusion. Each role knows exactly when their work starts, what they need to deliver, and when they are done.

Nobody asks what's next. The workflow already knows.

Product Manager Tool World

e.g. Asana, Jira, Linear, Trello

Who Lives Here

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

Tracks status, assignments, and notifications. The shared space everyone sees.

Product Owner
Create Ticket
/draftCreate a new ticket using the contract template. Claude structures the goal, context, and requirements from the Product Owner'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

QA
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 → Product OwnerDEV sends ticket back when requirements are wrong or incomplete. Product Owner 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

What Lives Here

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
/implement Execute the implementation plan
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
QA
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 feature, improvement, or fix follows a strict, trackable path to ensure quality and alignment across all teams. Transparency is maintained at every step.

Draft & Refining

Defining the core goal, historical context, and measurable hard requirements.

Designing

Attaching Figma specs, component mapping, and defining UX flows and edge cases.

Ready for Dev

The Contract is locked. All open questions are fully resolved. Engineering takes over.

In Progress

Blueprint architecture generated by AI, code implementation actively underway.

Done

Quality gates passed, code is merged, and deployed to the production environment.

Drafting & Refining

The Product Owner initiates the ticket. This phase relies heavily on AI to build a comprehensive context and set strict boundaries for the feature.

Initial Draft

/draft

Claude interrogates the Product Owner, maps out existing endpoints, and proposes the initial goal, context, and testable requirements.

Soft Gate

Warning

The AI checks for missing criteria and flags them. The ticket must remain in Refining until all critical open questions are answered.

Design Handoff

If UI changes are required, the ticket moves to Designing. The designer maps visuals directly to our existing component library to minimize custom code.

Figma attachments and visual specifications provided
Explicit mapping to existing components (Button, Dropdown)
UX edge cases handled (loading states, errors, empty states)

Development

Development begins only when the hard gates are passed. The AI generates the implementation plan based strictly on the finalized Contract.

Hard Gate: Ready for Dev Required

Open Questions must be entirely empty. The Contract must be fully locked. If scope or requirements change mid-flight, the ticket must return to Refining.

Blueprint Generation

/scaffold

The developer prompts the AI to read the contract and output the technical architecture: specific file changes, API payloads, and state management updates.

View Blueprint Template

Review & QA

Every pull request must explicitly satisfy the testable acceptance criteria defined in the Contract's Requirements section.

Code passes all automated tests linked to the original requirements.
Designer independently verifies visual mapping matches the Figma spec.
Performance constraints are validated in CI/CD pipeline before merge.