From issue to production — every step, every gate, every artifact
0
Steps
0
Phases
0
Artifact Types
Five phases from problem to production
Frame
triage, frame
Shape
analyze*, spec
Build
plan, implement, pr
Verify
validate, review, fix*
Ship
promote*, cleanup*
* = conditional step (skipped based on tier or outcome)
Three tiers, one pipeline
≤3 files, no architecture, no risk
Clear scope, single domain
New architecture, unclear requirements, >2 domains
Skip Matrix
| triage | frame | analyze | spec | plan | implement | pr | validate | review | fix | promote | cleanup | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| S | skip | skip | skip | skip | cond | cond | cond | |||||
| F-lite | skip | skip | cond | cond | cond | |||||||
| F-full | skip | cond | cond | cond |
Key insight File count alone doesn't determine tier. A 50-file mechanical change may be S, while a 3-file rate limiter is F-full.
Define the problem
Goal
Categorize and assign the issue
Artifact
GitHub issue with size/priority labels
Gate
Issue exists with clear title and body
Goal
Define the problem, constraints, and scope
Artifact
artifacts/frames/{slug}.mdx
Gate
User approves frame
S-tier skips framing — goes straight to implement
Design the solution
Goal
Deep technical exploration — risks, alternatives, recommendations
Artifact
artifacts/analyses/{N}-{slug}.mdx
Gate
User approves analysis
Goal
Define what we'll build — acceptance criteria, breadboard, slices
Artifact
artifacts/specs/{N}-{slug}.mdx
Gate
User approves spec
F-lite skips analysis — frame is sufficient context for spec
Write the code
Goal
Break spec into tasks, pick agents, define order
Artifact
artifacts/plans/{N}-{slug}.mdx
Gate
User approves plan
Goal
Create worktree, spawn agents, write code
Test-first: RED → GREEN → REFACTOR
Goal
Package work for review
$ gh pr create --base staging
Agent Routing
Frontend
frontend-dev
Backend
backend-dev
CI/CD
devops
Tests
tester
Docs
doc-writer
Test-first: tester writes failing tests, then domain agents implement
Review and fix
Goal
Run all quality gates
Goal
Fresh agents review code they didn't write
No agent reviews code it wrote
Goal
Apply accepted review findings
Auto-apply → /1b1 walkthrough → domain fixers
Fresh agents = no implementation bias
Release and clean up
Goal
Merge staging → main with version bump and changelog
Standalone via /promote — not auto-triggered by /dev
Goal
Remove stale worktrees and branches
$ git worktree remove
$ branch deletion
Promotion batches all staging changes into one release
Artifacts persist — sessions don't have to
Session dies → restart → same progress
Artifact Types
frame
What's the problem?
artifacts/frames/
analysis
How deep is it?
artifacts/analyses/
spec
What will we build?
artifacts/specs/
plan
How do we build it?
artifacts/plans/
Every phase transition requires your approval
Frame
Shape
Build
Verify
Ship
Structured Choices
Every choice presented as structured options — never plain-text questions
Clear Roles
Human decides, Claude orchestrates, agents specialize
Human-in-the-Loop
Not fully autonomous — intentionally human-in-the-loop
Automated Quality Gates
pre-commit
Biome lint + format
commit-msg
Commitlint conventional
pre-push
lint + typecheck + tests + i18n
The workflow is clear. Now let's explore the tools and patterns that power it.
Git hooks and Claude Code hooks enforce quality at every step — no human action needed
Git Hooks (Lefthook)
Triggered by git operations — block bad code before it reaches the repo
pre-commitBiome check — lint + format every staged file
commit-msgCommitlint — enforce conventional commit format
pre-pushFull suite — lint, typecheck, tests, i18n validation, license check
Claude Code Hooks
Triggered by tool use — enforce patterns during AI-assisted development
PostToolUseAuto-format files after every Write/Edit with Biome
PreToolUseBlock 'bun test' (must use 'bun run test'), warn on sensitive file access
Key insight: Hooks run automatically — they don't require human attention. They catch mistakes before they compound.
Claude Code uses your tools, not just its own
Issue Dashboard
Live view of issues, status, and dependencies. Runs alongside bun run dev at port 3333.
$ bun run dashboard
visibility without context-switching
External Tool Connections
Claude Code connects to GitHub, Vercel, Postgres, and any MCP-compatible service. Agents call these tools like any other.
Custom CLI Tooling
Aliases, tmux layouts, dev:clean, db:branch:create — Claude Code drives your entire local toolchain.
$ bun run dev:clean
$ bun run db:branch:create --force feat
$ bun run dashboard
Pro Tips
localhost:3000code ./vision.mdxAgents don't just write code — they operate your entire toolchain
Same brief, different minds — pick the best result
Parallel Domains
frontend-dev + backend-dev + tester work concurrently on the same issue via shared task list
Fresh Reviewer
No agent reviews code it wrote. Always a different agent for review — eliminates implementation bias
Escalation
Agent hits a blocker → creates follow-up task → notifies lead. Work never silently stalls
A plugin is a full capability bundle
Skill
Plugin
Workflow
The Roxabi boilerplate is a plugin: /dev, /promote, 9 agents, Biome formatter hook, all bundled together
Integration
Connect Claude to external systems via MCP: GitHub issues, Linear tickets, Vercel deployments, Slack notifications
Knowledge
Inject live documentation into agent context via MCP servers
Without: stale training data
With Context7: live docs at query time
Plugins are composable — stack multiple in one project via .claude/plugins/
Domain plugins bring the same AI-powered workflow to every team — not just developers.
Product Management
Marketing
Design
Legal
Sales
One /install. Your whole team unlocks AI-powered workflows.
Every push is automatically validated. Every merge is automatically deployed.
Continuous Integration
Pre-commit — Biome auto-formats on every file save
Pre-push — lint + typecheck + tests + i18n + license
GitHub Actions — 5 parallel jobs on every PR
E2E — Playwright on PR, full matrix on main/staging
Continuous Deployment
feat/* branch
→ Vercel preview deploy
staging branch
→ Vercel preview deploy
main branch
→ Vercel production deploy
Zero manual deploy steps — push to staging, promote to main, Vercel handles the rest
Automated PR review — triggered by GitHub, not by you
How it works
PR opened or pushed → workflow triggers
Preflight: skip if diff > 2 000 lines
claude-code-action@v1 spins up Claude Code in CI
Claude reviews the diff, auto-fixes safe issues, commits if needed
Posts structured comment: Auto-fixed + Manual action needed
The workflow config
- uses: anthropics/claude-code-action@v1
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
base_branch: ${{ github.base_ref }}
claude_args: >-
--max-turns 25
--allowed-tools Bash,Read,Edit,Write,Glob,Grep
prompt: |
Review the diff, auto-fix safe issues,
post structured comment.Formal notation rewrite for skills and agents
## Step 1 — Parse Input First, look at the arguments. If an issue number is provided (like #42), fetch the GitHub issue using the gh CLI tool to get the title and body. If the issue does not exist, stop execution and inform the user that the issue was not found. If free text is provided instead of an issue number, search for matching issues using the gh issue list command with the search parameter. If a matching issue is found, ask the user if they want to use it. If not, create a new issue or proceed without one.
## S0 — Parse
#N ⇒ `gh issue view N --json title,body`
¬∃ issue ⇒ halt
Free text ⇒ `gh issue list --search "{text}"`
∃ match ⇒ AskUserQuestion: Use #{N} | Create | Skip## Step 1 — Parse Input First, look at the arguments. If an issue number is provided (like #42), fetch the GitHub issue using the gh CLI tool to get the title and body. If the issue does not exist, stop execution and inform the user that the issue was not found. If free text is provided instead of an issue number, search for matching issues using the gh issue list command with the search parameter. If a matching issue is found, ask the user if they want to use it. If not, create a new issue or proceed without one.
Every skill and agent in this project is compressed
Where we're headed — projects to watch and features in the pipeline.
On the Roadmap
Observability Stack
Production monitoring, tracing & analytics dashboards
Public API & Dev Platform
REST SDK surface, API keys, webhooks & developer portal
Code Quality & Security
Automated security auditing on every PR
Coverage thresholds enforced in CI
Biome upgrade path & strict rule expansion
Dependency license & vulnerability scanning