AI Tooling for JBCT

Claude Code integration for Java Backend Coding Technology - skills, agents, and commands for AI-assisted development.

The JBCT Toolchain

JBCT ships three complementary tool families. This page covers the AI tools; the other two have their own pages:

• AI tools (this page) - Claude Code skills and subagents: learning the patterns, generating JBCT code, and reviewing for compliance.
• JBCT CLI (jbct) - a fast command-line formatter and linter that enforces JBCT structure deterministically; ideal for pre-commit hooks and CI/CD. See CLI Tools.
• Maven plugin - the same formatting and lint checks wired into the build, so they run as part of mvn verify. See Maven Plugin.

The CLI and Maven plugin keep structure mechanically correct on every build; the AI tools add context-aware generation and review on top. Together they cover authoring, verification, and review.

Overview

JBCT provides four AI tools for Claude Code:

Tool	Type	Purpose
jbct	Skill	Learning, quick reference, understanding patterns
jbct-coder	Subagent	Code generation following JBCT patterns
jbct-reviewer	Subagent	Code review for JBCT compliance
jbct-review	Skill/Command	Parallel review with 10 focused workers

Installation

Quick Install (All Tools)

# Clone repository
git clone https://github.com/siy/coding-technology.git
cd coding-technology/ai-tools

# Install skills and agents
cp -r skills agents ~/.claude/

Verify Installation

./check-drift.sh

Reports any skill or agent whose installed copy has diverged from this repo, alongside the other staleness checks below. Re-run cp -r skills agents ~/.claude/ to reconcile.

Maintenance

Skills are installed away from this repo, so a stale reference here becomes an invisible wrong answer there. Two scripts keep that from happening; both run in CI (.github/workflows/checks.yml).

./check-drift.sh                    # references, version pins, installed-copy divergence
python3 sync-book-blocks.py --check # book-owned blocks still match the books
python3 sync-book-blocks.py --write # regenerate them after a book edit

check-drift.sh flags references to retired documents, links that do not resolve, links that escape their skill directory (those cannot survive installation — cite the book by its pragmatica.dev URL), Pragmatica Core pins that disagree with the declared canonical version, and book version headers that disagree with the book’s own CHANGELOG.md.

sync-book-blocks.py copies enumerable rules the books own — naming vocabularies, ordering rules, catalogs — into the tooling between <!-- book:<id> --> markers. The book is the source; those regions are build output, so edit the book and regenerate. A renamed book heading fails extraction rather than silently leaving a stale copy.

Manual Verification

ls ~/.claude/skills/jbct/SKILL.md
ls ~/.claude/skills/jbct-review/SKILL.md
ls ~/.claude/agents/jbct-coder.md
ls ~/.claude/agents/jbct-reviewer.md

---

JBCT Skill

Purpose: Learning JBCT principles, quick reference, understanding patterns.

Activation: Automatic when working with Result, Option, Promise types, value objects, use cases, or JBCT patterns.

When to Use

• Learning JBCT principles and patterns
• Quick reference for API usage and examples
• Understanding when to use which pattern
• Questions about monadic composition, error handling, or validation

Structure

The skill uses progressive detalization:

jbct/
├── SKILL.md                      # Entry point with quick reference
├── fundamentals/                 # Core principles
│   ├── four-return-kinds.md     # T, Option, Result, Promise
│   ├── parse-dont-validate.md   # Value object patterns
│   └── no-business-exceptions.md # Typed failures with Cause
├── patterns/                     # Six structural patterns
│   ├── leaf.md                  # Atomic operations
│   ├── sequencer.md             # Sequential composition
│   ├── fork-join.md             # Parallel operations
│   ├── condition.md             # Branching logic
│   ├── iteration.md             # Collection processing
│   └── aspects.md               # Cross-cutting concerns
├── use-cases/                    # Use case design
│   ├── structure.md             # Anatomy and conventions
│   └── complete-example.md      # RegisterUser walkthrough
├── testing/                      # Testing strategies
│   └── patterns.md              # Functional assertions
└── project-structure/            # Project organization
    └── organization.md          # Vertical slicing

Quick Reference Topics

The skill provides immediate access to:

• Four Return Kinds: T, Option<T>, Result<T>, Promise<T>
• Parse, Don’t Validate: Making invalid states unrepresentable
• Six Structural Patterns: Leaf, Sequencer, Fork-Join, Condition, Iteration, Aspects
• Use Case Design: Factories, validated inputs, step composition
• Naming Conventions: Factory methods, validated inputs, error types
• Testing Patterns: Functional assertions with onSuccess/onFailure

Example Interactions

User: "How do I create a value object with validation?"
Claude: [Uses jbct skill to explain parse-don't-validate pattern with example]

User: "When should I use Result vs Promise?"
Claude: [Uses jbct skill to explain Four Return Kinds decision tree]

User: "Show me Fork-Join pattern"
Claude: [Uses jbct skill to show Promise.all/Result.all examples]

---

JBCT Coder Subagent

Purpose: Autonomous code generation following JBCT patterns.

Invocation: "Use jbct-coder to implement..." or Task tool with subagent_type: "jbct-coder"

Capabilities

• Complete use case implementations with all components
• Value objects with validation and error types
• Adapters with proper exception handling
• Test suites following JBCT patterns
• Deterministic code generation following all JBCT rules

What It Generates

Component	Description
Use case interface	Request, Response, execute signature
ValidRequest	Static factory with Result.all()
Step interfaces	Single-method interfaces for composition
Value objects	Parse-don’t-validate pattern
Error types	Sealed interfaces with Cause
Factory method	Lambda-returning factory
Tests	Validation, happy path, failure cases

Example Usage

User: "Use jbct-coder to implement a RegisterUser use case"

Claude: [Generates complete implementation]
- RegisterUser interface with Request/Response
- ValidRequest with email/password validation
- CheckEmail, HashPassword, SaveUser steps
- RegistrationError sealed interface
- registerUser() factory returning lambda
- RegisterUserTest with all test cases

Generation Algorithm

The coder follows a deterministic algorithm:

1. Parse requirements → Extract entities, operations, constraints
2. Design structure → Map to JBCT patterns
3. Generate value objects → Parse-don’t-validate factories
4. Generate use case → Interface, steps, factory
5. Generate tests → Validation, happy path, failures
6. Verify compliance → Check against JBCT rules

---

JBCT Reviewer Subagent

Purpose: Comprehensive code review for JBCT compliance.

Invocation: "Use jbct-reviewer to check..." or Task tool with subagent_type: "jbct-reviewer"

Review Areas

Category	What It Checks
Return Types	Four Return Kinds, no Void, no Promise<Result<T>>
Value Objects	Factory patterns, immutability, validation at construction
Use Cases	Structure, composition, lambda factories
Patterns	Correct use of Leaf, Sequencer, Fork-Join
Composition	Lambda complexity, fold() abuse, method references
Null Policy	Option usage, no null checks in business logic
Thread Safety	Immutability, no shared mutable state
Naming	Factory conventions, zone-appropriate verbs
Testing	Functional assertions, organization

Review Output Format

# JBCT Code Review Summary

## 🎯 Overall JBCT Compliance
**Compliance Level**: ✅ COMPLIANT | ⚠️ PARTIAL | ❌ NON-COMPLIANT
**Recommendation**: ✅ APPROVE | ⚠️ APPROVE WITH CHANGES | ❌ REQUEST CHANGES

## 🔒 Critical JBCT Violations
[Violations with file:line, code quotes, fixes]

## ⚠️ JBCT Warnings
[Pattern misuse, structural issues]

## 🛠️ Suggestions
[Naming conventions, style improvements]

## 🧹 Nitpicks
[Minor formatting issues]

Example Usage

User: "Use jbct-reviewer to check my RegisterUser implementation"

Claude: [Reviews all files, produces structured report]
- Checks return types
- Validates value object factories
- Verifies lambda complexity
- Reports findings with severity levels

---

JBCT Review Command

Purpose: Thorough parallel review using 10 focused workers plus aggregation.

Invocation: /jbct-review command in Claude Code

Usage

/jbct-review                              # Full codebase, all focus areas
/jbct-review src/main/java                # Specific path
/jbct-review --focus="Composition,Null"   # Specific areas only
/jbct-review src --focus="ValueObjects"   # Combined

Focus Areas (10)

Short Name	What It Checks
ValueObjects	Factory patterns, immutability
UseCases	Structure, composition, lambda factories
ReturnTypes	Result/Promise, Void→Unit, no exceptions
Structural	Leaf, Sequencer, Fork-Join patterns
Composition	fold() abuse, lambda complexity
Null	Option usage, null policy
ThreadSafety	Immutability, shared state
Naming	Factory conventions, zones, acronyms
Testing	Assertions, organization
CrossCutting	Security, performance, logging

How It Works

1. Parse arguments (path, focus areas)
2. Discover all Java files in target path
3. Launch 10 parallel workers (one per focus area)
4. Each worker reviews ALL files for its specific area
5. Wait for all workers to complete
6. Launch aggregator to consolidate reports
7. Output unified report with deduplication

Example Execution

User: /jbct-review src/main/java

1. Discover: 47 Java files found
2. Launch 10 parallel workers:
   - Worker 1: focus="Value Objects"
   - Worker 2: focus="Use Cases"
   - ...
   - Worker 10: focus="Cross-Cutting Concerns"
3. Wait for all workers
4. Aggregate results
5. Output: 3 Critical, 12 Warning, 8 Suggestion, 5 Nitpick

Benefits

• Thoroughness: Narrow focus = deeper analysis
• Speed: Parallel execution of all 10 workers
• Deduplication: Aggregator removes duplicate findings
• Balanced load: Focus areas grouped for even distribution

---

When to Use Which Tool

Scenario	Tool
Learning JBCT patterns	jbct skill (automatic)
Quick API reference	jbct skill
Implementing new use case	jbct-coder
Implementing value objects	jbct-coder
Writing tests	jbct-coder
Review single file	jbct-reviewer
Review PR/branch	jbct-review (/jbct-review)
Full codebase audit	jbct-review
Check specific patterns	jbct-review with --focus

---

Integration with JBCT CLI

For automated checks in CI/CD, use JBCT CLI:

# Check if installed
jbct --version

# Format + lint
jbct check src/main/java

The AI tools complement the CLI:

• CLI: Automated, fast, lint + format checks, CI/CD integration
• AI tools: Context-aware, deeper analysis, explanations, code generation

---

Pragmatica Core

All tools use Pragmatica Core 1.0.0-rc1 for functional types.

<dependency>
   <groupId>org.pragmatica-lite</groupId>
   <artifactId>core</artifactId>
   <version>1.0.0-rc1</version>
</dependency>

Library documentation: https://central.sonatype.com/artifact/org.pragmatica-lite/core

---

Resources

• JBCT book - Complete technical reference
• CLI Tools - Command-line formatting and linting
• Maven Plugin - Build integration
• GitHub Repository