@uditakhouri/branerail
Advanced tools
CTO-level architectural skill for Claude Code. Branerail forces design before you code.
A production-grade skill for Claude Code that enforces CTO-level thinking in AI-native development. This skill moves beyond code generation to architectural design, resilience patterns, and systems thinking.
Branerail is triggered whenever you're building, reviewing, or thinking about complex systems. It:
Use this skill whenever you encounter: architecture, scale, resilience, state ownership, blast radius, observability, distributed systems, design.md, code review.
This skill now includes active automation to enforce architectural rigor. Once installed, you can use these tools to audit your system:
branerail-audit: Scans your project root to ensure you have the required CLAUDE.md, /specs, and DESIGN.md in place.branerail-chaos: Parses your architectural specs and generates testable "Chaos Prompts" to verify if your resilience logic actually works.DESIGN.md Integration: Uses Google's standard for visual tokens; compatible with npx @google/design.md.Before shipping any system, answer these three questions with certainty:
What is the single source of truth for each piece of mutable data?
How do you know if the system is working? What tells you when it's failing?
Can you trace the blast radius of every component?
Branerail_skill/
├── SKILL.md # Main skill (27KB, comprehensive)
├── references/
│ ├── spec_template.md # Architectural specification template
│ ├── DESIGN_template.md # Visual design system template (DESIGN.md)
│ └── code_review_checklist.md # Code audit checklist for Claude Code
└── README.md # This file
Size: ~27KB Sections:
Purpose: Template for writing architectural specifications before coding
Includes:
Purpose: Google's DESIGN.md format for visual design system consistency
Includes:
Why DESIGN.md:
Purpose: Comprehensive checklist for auditing AI-generated code
Sections:
Usage: Run through this checklist when reviewing code generated by Claude Code.
You: "I need to build a checkout system. Where should I start?"
Claude (with Branerail):
1. Design before you code: "Sketch the architecture (boxes and arrows)"
2. Answer the three pillars
3. Write a spec (use references/spec_template.md)
4. Then ask Claude Code to generate code based on the spec
You: [Paste AI-generated code]
You: "Is this architecturally sound?"
Claude (with Branerail):
Runs through code_review_checklist.md:
- Spec compliance? ✓
- State ownership clear? ✗ [Issue found]
- Error handling? ✓
- Observability? ✓
- [Returns detailed audit with issues and fixes]
You: "We have user service → order service → payment gateway.
What happens if payment gateway goes down?"
Claude (with Branerail):
1. Analyzes blast radius
2. Identifies cascade failures
3. Suggests patterns (circuit breaker, queue, retry)
4. Provides implementation guidance
You: "Create our DESIGN.md to ensure all UI is on-brand"
Claude (with Branerail):
1. References DESIGN_template.md
2. Asks about brand colors, typography, components
3. Generates DESIGN.md with tokens and validation
4. Provides CLI commands to lint and export
# CLAUDE.md - Instructions for Claude Code
You are a CTO-level code generator with Branerail guidance.
When building new features:
1. Reference the architectural spec at /specs/[feature].md
2. Use the Branerail skill to audit your code
3. Verify the Three Pillars are answered
4. Include structured logging and metrics
5. Handle all failure modes listed in the spec
When building UI:
1. Reference /DESIGN.md for colors, typography, components
2. Ensure WCAG AA contrast ratios
3. Use design tokens consistently
4. Validate with: npx @google/design.md lint DESIGN.md
Use references/spec_template.md to create architectural specs for each major component.
Use references/DESIGN_template.md to define your visual design system. Export tokens to Tailwind.
Use references/code_review_checklist.md to audit code from Claude Code before merging.
Write to DB first → Update cache → Return result
(Ensures cache never has newer data than DB)
External service fails 5x in a row
→ Circuit opens
→ Fail fast (don't retry)
→ After 60 seconds, try again (half-open)
→ If success, close circuit
Don't store state; store events
→ Event: "Order created"
→ Event: "Payment charged"
→ Event: "Order shipped"
→ Replay events to reconstruct state
Separate read model from write model
→ Writes go to write DB (optimized for transactions)
→ Reads go to read DB (optimized for queries)
→ Eventual consistency between them
Scenario: Build a checkout system that handles 1000 orders/sec, resilient to payment gateway failures.
Using Branerail:
Design Phase
Spec Contents
# Order Processing Spec
## Inputs
- User ID, product IDs, amounts, currency
## Outputs
- Order ID, status (pending/completed/failed), confirmation
## State Ownership
- Order Service: order status (DB)
- Payment Service: payment receipt (DB)
## Failure Modes
- Payment timeout: Retry 3x with exponential backoff
- Payment rejected: Alert user, order stays pending
- Database down: Circuit breaker, fail fast
Code Generation (Claude Code)
Prompt: "Implement order processing per /specs/orders.md
- Handle all failure modes
- Log every operation with orderId, status, latency
- Emit metrics: order count, payment latency p50/p95/p99, error rate
- Add circuit breaker for payment gateway
- Validate against DESIGN.md for UI"
Code Review (Checklist)
Deployment
After using this skill, score yourself:
| Criterion | Score |
|---|---|
| State ownership is clear (single source of truth) | 0–3 |
| Observability is sufficient (logs, metrics, tracing) | 0–3 |
| Failure handling covers all modes (spec + extras) | 0–3 |
| Dependencies are explicit and documented | 0–3 |
| Blast radius is understood (no surprises) | 0–3 |
| Code is tested (happy path + failure modes) | 0–3 |
| Performance targets are met or on-track | 0–3 |
| Security is defensible (no obvious holes) | 0–3 |
Target: 2+ on all dimensions. Anything < 2 is a risk.
If you answer YES to all 15, your system is sound.
# Validate DESIGN.md against spec
npx @google/design.md lint DESIGN.md
# Check WCAG contrast ratios
npx @google/design.md lint DESIGN.md --wcag
# Compare two versions
npx @google/design.md diff DESIGN.md DESIGN-v2.md
# Export to Tailwind
npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
# Export to W3C DTCG
npx @google/design.md export --format dtcg DESIGN.md > tokens.json
| Version | Date | Changes |
|---|---|---|
| 1.0.0 | 2026-04-27 | Initial release. Complete skill with bundled templates and checklists. Integrated Google's design.md standard. CTO-level guidance for Claude Code integration. |
This skill is designed for builders who refuse to let their judgment atrophy. Use it to think deeply before coding. Use it to audit AI-generated code. Use it to build resilient systems that scale.
Questions? Feedback? Open an issue or PR on the skill repository.
Summary: Branerail is your CTO-level guide in an AI-native world. It moves you from "coding faster" to "architecting better." Use it to build systems that are resilient, observable, maintainable, and right.
FAQs
CTO-level architectural skill for Claude Code. Branerail forces design before you code.
We found that @uditakhouri/branerail demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Product
Socket Threat Intel now shows which malware campaigns were blocked or detected in your organization, with links to scans and Firewall events.
Security News
Fixes for eMudhra and Brotli are out. Getting them everywhere they’re needed means tracking down bundled libraries, runtimes, and certificate stores.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.