production-grade

name

production-grade

description

The build half of the Blackbox Protocol — a vendored fork of production-grade. Delivers production-ready systems: constraint-driven architecture, tested code, security audit, CI/CD, documentation, adversarial review, and the v5.5 loop engine. DISPATCHED BY THE ROUTER, NOT SELF-TRIGGERING: it is invoked by /build once a signed acceptance contract exists, and must not fire ahead of one. If you reached this skill without a frozen contract, stop and run /freeze first — building against an unsigned requirement produces work that nothing can certify.

Production Grade

!git status 2>/dev/null || echo "No git repo detected" !cat CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found" !ls Claude-Production-Grade-Suite/ 2>/dev/null || echo "No existing workspace" !cat .production-grade.yaml 2>/dev/null || echo "No config file — defaults apply" !cat Claude-Production-Grade-Suite/.protocols/visual-identity.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/freshness-protocol.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/receipt-protocol.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/boundary-safety.md 2>/dev/null || true

## You are the build half of the Blackbox Protocol

Read build/UPSTREAM.md before proceeding. Five things differ from upstream, and each one changes what you are for.

1. The requirement is .blackbox/intent/CONTRACT.md, and it is signed. Do not run discovery. Do not interview the user about what they want. A human has already read and signed a disambiguated EARS contract, and it is hashed — the scope guard blocks writes to .blackbox/intent/ entirely.

Build what it says. Do not implement beyond it: anything outside the contract will not be verified, and shipping unverified surface is how a clean certificate becomes misleading. Do not narrow it either — if a criterion turns out harder than expected, say so and stop. The human can amend and re-sign. Quietly building something easier that passes is the most damaging defect available to you, because it is invisible on a green certificate.

2. Your gates are advisory. Your receipts, your three approval gates, your adversarial review — run all of them, they make the code good. None of them close a criterion. Your strongest possible terminal claim is "I believe this is done", which is precisely the claim /verify exists to test. It will sometimes come back and say you were wrong. That is the system working, not a failure of your pipeline.

3. You cannot see the acceptance campaign. .blackbox/runs/, .blackbox/sealed/, .blackbox/certificate/ and the harness drivers are blocked by hook. This is not bureaucracy: if you could see the cases you would satisfy the cases instead of the criteria, and the certificate would measure your aim rather than your work.

4. Implement the Access Contract. harness/ACCESS.md states — written blind, from the criteria alone — what the verifier must be able to control and observe. Implement those seams. You can see the code, so this is cheap for you and impossible for them. Gate test-only routes behind an environment flag. If a control genuinely cannot be provided, say so explicitly: it becomes UNVERIFIED on the certificate with your reason. Never substitute something weaker in silence.

5. On rework you get the criterion, not the case. A failed verification hands you the violated criterion, observed-versus-expected behaviour, and a minimal reproduction — never the campaign, never the case that caught it. Each run draws fresh representatives from the same equivalence classes, so a fix that satisfies only the values you were shown will fail the next draw. Fix the criterion, not the reproduction.

Set export BLACKBOX_ROLE=build before you start. Without it the scope guard is inert, and an inert guard makes the independence claim on the certificate false.

Overview

Adaptive meta-skill orchestrator that enhances Claude Code's development output. Analyzes the user's request, identifies which skills are needed, builds a minimal task graph, and executes — from a single code review to a full 14-skill greenfield build.

Without this skill: Claude Code produces code. With this skill: Claude Code produces architecture + tested code + security audit + CI/CD + documentation.

14 skills, one orchestrator. The orchestrator routes to the right skills based on what the user actually needs. No forced full-pipeline execution for everyday tasks.

All skills are bundled in this plugin. Single install, everything included.

When to Use

• Building a new SaaS, platform, or service from scratch (full pipeline)
• Adding a feature to an existing codebase
• Hardening code before launch (security + QA + review)
• Setting up CI/CD, Docker, Terraform for existing code
• Writing tests for existing code
• Reviewing code quality or architecture conformance
• Designing architecture or API contracts
• Writing documentation for existing systems
• Performance optimization or reliability engineering
• Any task that benefits from structured, production-quality execution
• User says "build me a...", "add [feature]", "review my code", "set up CI/CD", "write tests", "harden this", "document this"

Request Classification

Before any execution, classify the user's request into a mode. This determines which skills run and how.

Step 1 — Analyze the request:

Read $ARGUMENTS and the user's message. Classify into one of these modes:

Mode	Trigger Signals	Skills Involved
Full Build	"build a SaaS", "production grade", "from scratch", "full stack", greenfield intent	All 14 skills, full DEFINE→BUILD→HARDEN→SHIP→SUSTAIN pipeline
Feature	"add [feature]", "implement [feature]", "new endpoint", "new page", "integrate [service]"	PM (scoped) → Architect (scoped) → BE/FE → QA
Harden	"review", "audit", "secure", "harden", "before launch", "production ready" (on EXISTING code)	Security + QA + Code Review (parallel) → Remediation
Ship	"deploy", "CI/CD", "containerize", "infrastructure", "terraform", "docker"	DevOps → SRE
Test	"write tests", "test coverage", "test this", "add tests"	QA
Review	"review my code", "code review", "code quality", "check my code"	Code Reviewer
Architect	"design", "architecture", "API design", "data model", "tech stack", "how should I structure"	Solution Architect
Document	"document", "write docs", "API docs", "README"	Technical Writer
Explore	"explain", "understand", "help me think", "what should I", "I'm not sure"	Polymath
Optimize	"performance", "slow", "optimize", "scale", "reliability"	SRE + Code Reviewer
Custom	Doesn't fit above patterns	Present skill menu, let user pick

Step 2 — Present or skip the plan:

Single-skill modes (Test, Review, Architect, Document, Explore): Skip plan presentation. Classify → invoke immediately. The intent is obvious — no overhead needed.

Multi-skill modes (Feature, Harden, Ship, Optimize, Custom): Present the plan for confirmation:

AskUserQuestion(questions=[{
  "question": "Here's my plan:\n\n"
    "[numbered list of skills and what each does]\n\n"
    "Scope: [light / moderate / heavy]",
  "header": "Execution Plan",
  "options": [
    {"label": "Looks good — start (Recommended)", "description": "Execute this plan"},
    {"label": "I want the full production-grade pipeline", "description": "Run all 14 skills, 5 phases, 3 gates"},
    {"label": "Adjust the plan", "description": "Add or remove skills from the plan"},
    {"label": "Chat about this", "description": "Free-form input"}
  ],
  "multiSelect": false
}])

Full Build mode: Always proceed to the Full Build Pipeline section below.

If the user selects "full pipeline" from any mode, switch to Full Build.

Step 3 — Execute the mode:

For non-Full-Build modes, use the lightweight execution flows below. For Full Build, use the Full Build Pipeline.

Mode Execution (Non-Full-Build)

All modes share these behaviors:

• Bootstrap workspace: mkdir -p Claude-Production-Grade-Suite/.protocols/ Claude-Production-Grade-Suite/.orchestrator/
• Write shared protocols (same as Full Build step 3, including visual-identity.md, freshness-protocol.md, receipt-protocol.md, boundary-safety.md, and loop-protocol.md)
• Read .production-grade.yaml for path overrides
• Read existing workspace state if present
• Engagement mode + parallelism: ask ONLY if mode involves 3+ skills. For 1-2 skill modes, use Standard engagement + Sequential execution (overhead of asking isn't worth it).
• Cleanup: After mode completion (or gate rejection), run TeamDelete(team_name="production-grade") if a team was created. Never leave orphaned agents.

Non-Full-Build Visual Output

Mode banner (print on start for all non-Full-Build modes):

━━━ {Mode Name} Mode ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Scope: {what will be done}
  Skills: {skill list}
  Files: {N} across {M} services/directories (if applicable)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Multi-skill completion (for modes with 2+ skills):

┌─ {Mode Name} Complete ────────────────────── ⏱ {time} ─┐
│                                                          │
│  ✓ {Skill 1}    {concrete metrics}                       │
│  ✓ {Skill 2}    {concrete metrics}                       │
│  ✓ {Skill 3}    {concrete metrics}                       │
│                                                          │
│  {N}/{N} complete                                        │
└──────────────────────────────────────────────────────────┘

Single-skill modes (Test, Review, Architect, Document, Explore): The skill prints its own ━━━ [Skill Name] ━━━ header and [1/N] phase progress. No orchestrator-level completion box needed.

Feature Mode

Add a feature to an existing codebase. Lightweight DEFINE → BUILD → TEST.

1. Codebase scan — read existing code structure, framework, patterns
2. PM (Express depth) — 2-3 questions to scope the feature. Write a mini-BRD (user stories + acceptance criteria for this feature only)
3. Architect (scoped) — design how this feature fits the existing architecture. New endpoints, schema changes, component additions. NOT a full system redesign.
4. Build — Software Engineer and/or Frontend Engineer implement the feature
5. Test — QA writes and runs tests for the new feature
6. Optional: Review — Code Reviewer checks the new code against existing patterns

1 gate: After PM scoping (step 2), confirm scope before building.

Harden Mode

Security + quality audit on existing code. No building, pure analysis + fixes.

1. Codebase scan — read all existing code
2. Parallel: Security Engineer + QA Engineer + Code Reviewer analyze the code simultaneously
3. Consolidated findings — merge all findings, deduplicate, sort by severity
4. Present findings — severity grid with Critical/High detail
5. Remediation — fix Critical and High issues (with user confirmation)

1 gate: After findings (step 4), before remediation.

Visual flow:

━━━ Harden Mode ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Scope: Security + QA + Code Review on existing code
  Files: {N} across {M} services
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⧖ 3 agents analyzing in parallel...

  ✓ QA Engineer          {N} tests written, {M} passing       ⏱ Xm Ys
  ✓ Security Engineer    {N} findings ({M} Critical/High)     ⏱ Xm Ys
  ✓ Code Reviewer        {N} findings ({M} Critical/High)     ⏱ Xm Ys

━━━ Findings ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Critical   {N}    {description}
  High       {N}    {summary}
  Medium     {N}    —
  Low        {N}    —
  ─────────────
  Total      {N}    deduplicated by file:line
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Ship Mode

Get existing code deployed. Infrastructure + reliability.

1. Codebase scan — read existing code, identify services, dependencies
2. DevOps — Dockerfiles, CI/CD pipelines, IaC (Terraform/Pulumi), monitoring
3. SRE — SLO definitions, runbooks, alerting, chaos experiment plan

1 gate: After DevOps infra plan, before applying.

Test Mode

Write tests for existing code. Single skill.

1. Invoke QA Engineer directly against existing code
2. QA reads code, writes test plan, implements tests, runs them
3. Report results

0 gates. QA operates autonomously.

Review Mode

Code quality review. Single skill, read-only.

1. Invoke Code Reviewer directly
2. Review produces findings report
3. Present findings with severity distribution

0 gates. Read-only operation.

Architect Mode

Design or redesign architecture. Single skill.

1. Invoke Solution Architect
2. Full discovery interview (depth based on engagement mode)
3. Produces ADRs, diagrams, tech stack, API contracts, scaffold

1 gate: Architecture approval before scaffold generation.

Document Mode

Generate documentation for existing code. Single skill.

1. Invoke Technical Writer
2. Reads all code + existing docs
3. Generates API reference, dev guides, architecture overview

0 gates. Technical Writer operates autonomously.

Explore Mode

Thinking partner. Single skill.

1. Invoke Polymath
2. Research, advise, ideate — whatever the user needs
3. When ready, offer to hand off to any other mode

0 gates. Polymath manages its own dialogue.

Optimize Mode

Performance + reliability analysis. Two skills.

1. Code Reviewer — identify performance anti-patterns, N+1 queries, memory leaks
2. SRE — capacity analysis, scaling bottlenecks, SLO evaluation
3. Consolidated report — performance findings + reliability recommendations
4. Remediation — fix top issues

1 gate: After analysis, before fixes.

Custom Mode

User picks skills from a menu.

AskUserQuestion(questions=[{
  "question": "Which skills do you need?",
  "header": "Skill Selection",
  "options": [
    {"label": "Product Manager", "description": "Requirements, user stories, BRD"},
    {"label": "Solution Architect", "description": "System design, API contracts, tech stack"},
    {"label": "Software Engineer", "description": "Backend implementation"},
    {"label": "Frontend Engineer", "description": "UI components, pages, design system"},
    {"label": "QA Engineer", "description": "Tests — unit, integration, e2e, performance"},
    {"label": "Security Engineer", "description": "OWASP audit, STRIDE, vulnerability scan"},
    {"label": "Code Reviewer", "description": "Architecture conformance, code quality"},
    {"label": "DevOps", "description": "Docker, CI/CD, Terraform, monitoring"},
    {"label": "SRE", "description": "SLOs, chaos engineering, runbooks"},
    {"label": "Technical Writer", "description": "API docs, dev guides, architecture docs"},
    {"label": "Data Scientist", "description": "LLM optimization, ML pipelines, experiments"},
    {"label": "Chat about this", "description": "Free-form input"}
  ],
  "multiSelect": true
}])

Execute selected skills in dependency order. If user picks conflicting skills, resolve via the authority hierarchy.

Auto-Update Check

Run BEFORE any execution (all modes). Silent if current. One prompt max if update exists.

Step 0 — version check:

1. Read ~/.claude/plugins/installed_plugins.json → find the production-grade@nagisanzenin entry → extract version (this is your local version)
2. WebFetch https://raw.githubusercontent.com/nagisanzenin/claude-code-production-grade-plugin/main/.claude-plugin/plugin.json → extract version (this is the remote version)
3. If WebFetch fails (offline, timeout, 404) → silently continue. Never block the pipeline over an update check.