adam bien's blog

An agent running on the AWS Bedrock AgentCore Runtime has to implement a minimal HTTP contract: POST /invocations answers requests, GET /ping reports health, both on port 8080. The JDK's built-in jdk.httpserver is sufficient.

The AWS Java Agent Core Runtime CDK quickstarter project implements the contract in vanilla Java 25 with zero external dependencies. The complete contract is implemented in a single interface:

public interface AgentRuntime {

    int AGENT_CORE_PORT = 8080;

    static String invokeAgent(String payload) {
        IO.println("invocation: " + payload);
        return """
            {"time":"%s"}""".formatted(Instant.now());
    }

    static String checkHealth() {
        return """
            {"status":"Healthy"}""";
    }

    static void serve() {
        HttpEndpoint.start(AGENT_CORE_PORT, AgentRuntime::invokeAgent, AgentRuntime::checkHealth);
    }
}

A second interface, HttpEndpoint, wires both routes on the JDK's HttpServer. Every import comes from the JDK. The sample agent answers each invocation with the current UTC time as JSON. Packaged with zb, the complete agent.jar is 5,440 bytes, and the endpoints are serving about 60 ms after JVM start (OpenJDK 25, Apple Silicon).

Deployment is also Java. The project ships with an AWS CDK app (the cdk module) that builds the agent's four-line Dockerfile (Amazon Corretto 25, the jar, an ENTRYPOINT) into an ARM64 container image asset and provisions the AgentCore runtime from it. The image is built and pushed during cdk deploy. The system tests invoke the deployed agent with the AWS SDK's BedrockAgentCoreClient.

The project was developed with /sbce, the spec-driven BCE workflow: the AgentCore contract is declared as EARS requirements (Easy Approach to Requirements Syntax) in the business component's package-info.java, and @Requirement annotations (trimmed from the listing above) trace the boundary methods back to the spec.

The project is part of constructions.cloud, a collection of Java CDK templates and quickstarters.

Subscribe to airhacks.fm podcast via: spotify| iTunes

The /aws-cdk skill generates and reviews Java AWS CDK v2 projects organized as BCE (Boundary-Control-Entity) business components. Infrastructure code follows the same structure as a business application instead of accumulating as a flat list of resources. It ships as an AIrails skill: /aws-cdk.

The main tenet is the separation of stacks from constructs. A stack decides which resources deploy together and lives in boundary. A construct defines how a capability is configured, is reusable across stacks, and lives in control as a stateless factory, preferably an interface with static methods. Immutable data that describes infrastructure without creating it, like build specs and typed value objects, lives in entity.

The remaining ideas follow from that split:

1. Packages are business components named after the AWS capability they provision: s3, cloudfront, cognito, route53, stepfunctions. A component spanning multiple services is named after its domain responsibility.
2. A single CDKApp entry point loads configuration as typed Java records, applies tags, wires stacks in dependency order, and calls app.synth(). Stacks never read CDK context or environment variables; they receive typed records.
3. Regions are pinned in a central Stacks interface exposing StackProps constants. Account and region are never inlined in stack classes.
4. Stacks stay independent. A producing stack passes resource interfaces like IBucket or ITable to consumers, never stack instances.
5. For IAM, grant* methods on the target construct generate least-privilege policies. Explicit PolicyStatements are the fallback.
6. Synthesis stays deterministic and side-effect free: no SDK calls, no timestamps, no randomness during construction. Tests assert on the synthesized CloudFormation template instead of snapshots.

The skill composes with /bce and /java-conventions and ships with a domain-neutral project blueprint. It is also compatible with /sbce, the spec-driven BCE workflow: a capability spec describes one business component, and the code is iterated until it matches the spec. A compilable starter is available at AdamBien/aws-cdk-plain, and constructions.cloud collects example constructs and CDK applications.

A business component is a package named after a single responsibility, and the structure of a system is the sum of these components. The hard part is finding the names. Here is the simplest approach I know, three steps.

1. Say it. Describe what the system does in one sentence, in one breath.
2. Name it. Underline the essential verbs and nouns. Those are your component candidates, and verbs become nouns.
3. Test it. Drop every name that would fit another project. A name that transplants into any system says nothing about this one.

The method reverse-engineers reality. Take zb, a zero dependency builder:

"It discovers the Java sources, compiles them, packs an
 executable JAR, and runs the test hook after the build."

Verbs become nouns: discovers becomes discovery, compiles becomes compiler, packs becomes packer, and hook is already a noun. Open zb and you find exactly those packages: discovery, compiler, packer, hook. That sentence took about ten iterations. packer started as "jar creator", discovery started as "source", and hook did not exist yet.

An online shop: "customers browse the catalog, put products into a cart, place orders, and pay." That gives catalog, cart, orders, payments. Browse collapses into catalog, products are entities inside it. Customers is borderline: a component only when the system manages them, otherwise an entity inside orders.

Say it. Name it. Test it.

Part of the free Screaming Architecture with BCE course.

The airails.dev skills ship as a single "Any agent" bundle: a zip that contains a skills/ folder. Installing it is two steps.

1. Download the bundle.
2. Unzip it into your agent's config directory.

curl -LO https://github.com/AdamBien/airails/releases/download/skills/airails-skills.zip

unzip airails-skills.zip -d ~/.claude     # Claude Code
unzip airails-skills.zip -d ~/.copilot    # GitHub Copilot CLI
unzip airails-skills.zip -d ~/.agents     # Codex
unzip airails-skills.zip -d ~/.vibe       # Vibe

The zip carries a skills/ folder, so the parent directory is the only thing that changes. Unzip into ~/.claude and the skills land in ~/.claude/skills. The same bundle works for every agent, including Claude Code, GitHub Copilot CLI, Codex, and Vibe.

A business component (BC) is a package named after a single responsibility. Inside are up to to three sub-packages, always the same three names:

• boundary: the public API of the component. Coarse-grained, simple, opinionated.
• control: fine-grained, generic functions and methods.
• entity: the data.

Boundary, control, entity is the maximum, not a requirement. A component takes only the layers its responsibility needs. From zsmith, an agent harness:

• skills has all three. A public API, enough logic for a control, and its own data.
• memory is boundary and entity, no control. The logic is simple enough to sit in the boundary.
• claude, configuration, and llm are control only. claude is the class that talks to Anthropic, configuration reads properties. No exposed API, no data of their own.

The tools component shows all three from the implementation side:

zsmith.tools
├── boundary   execute a tool, check whether it runs in parallel
├── control    the tool implementations, like the read-file tool
└── entity     the annotations, the tool result, the tool use

The three layers have been stable since 1992. They never changed, there were no version updates, and they are well described across books and articles. That stability is also why LLMs work well with them.

A business component is a top-level package named after a single responsibility or feature, not after a technology. discovery, compiler, checkout, invoicing: reading the package names tells you what the system does. That is Screaming Architecture. The structure of a system is the sum of its business components.

Business components are not designed up front. They are created on the go: every new requirement becomes a new component.

zb, a zero dependency builder, grew exactly this way. The first requirement was finding the code. Sources can sit in src or src/main/java, so convention over configuration became a responsibility of its own: discovery.

Found code has to be compiled, then packaged into an executable JAR, then verified. Each need became its own component:

discovery, compiler, packer, hook

The packer creates the JAR. The first name was jar creator, too long. jc was too cryptic. A business component name is descriptive but short: no compound names, no abbreviations. The hook runs after a successful build, so zunit can execute the tests.

discovery, compiler, packer, and hook are domain components. They are first class: reading them reveals what zb does and how it is structured.

Subscribe to airhacks.fm podcast via: spotify| iTunes

I noticed that coding agents reach for Quarkus developer mode by default. They start quarkus:dev and keep it running.

An agent edits, then it has to observe the result before deciding the next move: compile error, test verdict, endpoint response.

• Live reload on the next request. The agent edits a resource. The system tests, running on a second Quarkus in Dev Mode, hit the live-reloaded endpoint over HTTP and report back. No rebuild, no restart on either side.
• Continuous Testing. Tests re-run on the affected code automatically. The agent gets red or green without asking for it.

The math is simple. A thirty-second restart is an annoyance for a developer who hits it five times an hour. For an agent iterating two hundred times, it is the entire budget. Cut the loop to a second and the agent spends its time changing code instead of waiting for the JVM.

The continuous-testing skill at airails.dev encodes this loop: after every change it builds, starts the server, and runs the unit, integration and system tests.

Fast iteration was always the point of Dev Mode. Agents just run into the payoff far more often than people do.

For java-cli applications there is no Dev Mode, but zb builds them so fast (< 1s) the loop stays just as tight. Another excuse to use it. 😀

The structure of a system should reveal its purpose. Robert C. Martin coined the term Screaming Architecture for this idea roughly 15 years ago. In the first episode of my BCE screencast course, I put it to the test: can you tell what a project does by reading its top-level package names? Production sources only, no tests.

zb:

compiler, hook, packer

zb stands for zero dependency builder. It compiles Java code, creates executable JARs, and runs unit tests as a hook. The packages describe exactly that.

lightmetal:

prompting, sampling, tokenization, tools

With basic LLM terminology, the packages point to local inference. lightmetal runs LLMs on the Apple Metal API via llama.cpp.

zsmith:

agent, memory, skills, tools, tui

zsmith is an agent harness. The structure explains itself.

All three projects organize code by domain responsibility, the idea behind BCE business components. A new tool goes into tools, agent persistence lives in memory, and code is found where expected. This applies to LLMs as well: an agent navigating packages named after responsibilities locates code without scanning the whole project.

Subscribe to airhacks.fm podcast via: spotify| iTunes

zbaseline is a zero-dependency Java 25 CLI that fetches the complete web platform feature set (currently ~1,171 features) from the webstatus.dev API and renders it into a single markdown snapshot with the Google Baseline status of every CSS, HTML and JavaScript feature.

The snapshot, written to stdout, is one markdown table sorted by feature id: Feature id, Name, Status (widely / newly / limited), and the dates a feature became newly or widely available. The header carries the snapshot date, the data source URL, and the rule for misses: a feature not in the snapshot is treated as uncertain.

The markdown format is intentional. The airails.dev web-conventions skill bundles such a snapshot for HTML and CSS generation.

zbaseline has zero external dependencies: JSON parsing relies on copied org.json sources, the build is plain zb, and the project was generated from the java-cli-app template following sbce.space principles.

Clone, run, and your agents stop guessing: github.com/adamBien/zbaseline

zws is a development web server in a single Java 25 source file on top of the built-in jdk.httpserver. It serves static files from a directory, sends no-cache headers, and opens the browser. Java 25 is the only prerequisite:

curl -O https://raw.githubusercontent.com/AdamBien/zws/main/zws
chmod +x zws
./zws [root-directory] --live --single

Without root-directory, zws serves the current directory.

With --live, zws watches the site root recursively with WatchService and injects a single line into every served HTML page:

The /reload endpoint speaks server-sent events: the connection stays open on a virtual thread, and every file change pushes an event that reloads the page. Save a file, the browser refreshes. Pure web standards, no WebSockets, no client library, no build step.

With --single, zws serves Single Page Applications with client-side routing: GET requests for paths that do not exist on disk and have no file extension (routes like /add) are answered with index.html, so deep links and reloads reach the application. Requests with a file extension still return 404, keeping typos visible.

The flags are independent and compose: with both active, SPA-fallback responses reload as well.

The airails.dev skills bundle zws as the development server: the generic web-conventions skill ships a copy, web-static serves generated sites with it for authoring (--live) and for the verification loop, and web-components relies on --single for SPA routing during development.

zws is part of z, a collection of zero-dependency Java projects.

DESIGN.md stores a design system as YAML token blocks inside a markdown file. Agents and developers can read, review, and diff it like any other document.

zdmd is a Java port of the reference TypeScript CLI: a zero-dependency Java 25 application packaged as a single executable JAR. It lints, diffs, and exports DESIGN.md token files. One JAR replaces node_modules for anyone working with design systems on the JVM:

zdmd                    # convert DESIGN.md into all formats, write tokens.css + tokens.json
zdmd lint  [--format json|md]
zdmd diff   [--format json|md]
zdmd export  --format  [--prefix ]

The bare launch is built for agents: it reads DESIGN.md from the current directory, writes every supported format (tokens.css and tokens.json), and prints the written filenames. No flags to remember.

Only web-standard export formats are supported: CSS custom properties and W3C Design Tokens (DTCG) JSON. Tailwind is intentionally out of scope. lint exits with 1 on errors and diff exits with 1 on regressions, so both plug directly into CI pipelines.

Installation requires nothing but Java 25+:

curl -fLO https://raw.githubusercontent.com/AdamBien/zdmd/main/zdinstall
chmod +x zdinstall
./zdinstall

zdmd was built with the spec-driven BCE workflow (sbce.space): each capability lives in its own business component, and the spec in package-info.java is the boundary contract. It is part of z, a collection of zero-dependency Java projects.

The bce.design quickstarter lost its entire build system: Node.js, npm, rollup, lockfiles. 777 lines deleted.

The toolchain existed for one reason: Redux Toolkit. It ships with transitive dependencies (immer, redux, reselect), so a bundler had to flatten it into a browser-loadable module.

Then Redux Toolkit got replaced with reduction.js, a 70-line, standards-based implementation of the used API, relying on structuredClone instead of Immer.

The only dependency left: lit-html. And lit-html is a single, self-contained, dependency-free ES module. The bundler's output was byte-for-byte its input. The whole machinery reduced to:

curl -fsSL https://registry.npmjs.org/lit-html/-/lit-html-3.3.3.tgz \
    | tar -xzO package/lit-html.js > app/src/libs/lit-html.js

Straight from the npm registry: no CDN, no middleman, the exact bytes npm install would deliver.

The vendored module is mapped with a standard import map in index.html:

<script type="importmap">
{
  "imports": {
    "lit-html": "/libs/lit-html.js",
    "@reduxjs/toolkit": "/reduction.js"
  }
}
</script>

Routing is implemented with the Navigation API and URLPattern, so there is no router dependency either.

Remove a dependency, and the tooling it dragged in disappears with it. Web standards are the best dependency: nothing to install, nothing to build, nothing to migrate.

A Package per Feature and Semantics over Bureaucracy showed BCE in a Java CLI application and claimed the convention is cross-technology. Proof: an events application built with web components and lit-html on plain web standards. No framework, no build; the store is reduction.js, 77 lines on structuredClone, and lit-html is the only runtime dependency. The src directory is a list of BCs:

src
├── creation
├── filter
├── inputs
├── localstorage
├── overview
├── preview
└── status

Inside each BC, the fixed names return. The filter component carries all three layers:

filter
├── boundary
│   └── Filter.js
├── control
│   └── FilterControl.js
└── entity
    └── FilterReducer.js

The mapping to the browser is direct. The boundary is the custom element: it renders the lit-html view and receives the DOM events, because in a frontend the external actor is the user. The control is a function that creates and dispatches an action. The entity is the state slice with its reducer: state has a home, here it is literally the store.

The dependency direction survives the technology switch: boundary calls control, control updates entity through the store, and the store re-renders the boundary. And layers stay optional: localstorage is control-only, preview is boundary-only.

A Java developer navigates this frontend without learning a new layout, and a frontend developer navigates lightmetal the same way. That is what fixed names buy.

Subscribe to airhacks.fm podcast via: spotify| iTunes

A Package per Feature made the case for the Business Component (BC): one package per responsibility. Inside a BC the next question appears immediately: where does a class go? In most projects that question spawns bureaucracy: naming debates, layout documents, style-guide meetings. BCE answers it once, with three fixed packages. The generation BC from lightmetal:

lm.generation
├── boundary
│   ├── LightMetal.java
│   ├── LightMetalChat.java
│   └── LightMetalText.java
├── control
│   └── TokenAccumulator.java
└── entity
    ├── Response.java
    └── Tps.java

The motivations:

1. No placement debates. Every class has exactly one obvious home. The three names are fixed, so reviews argue about the semantics, not bureaucracy, and every BC in every project reads the same way. The convention is cross-technology: the same three package names structure a Java server, a web frontend, or infrastructure code. MVC only names roles, and every MVC framework invented its own directory layout. BCE is the only architectural standard where the layer names are the structure itself, fixed for over three decades.
2. One entry point for the outside world. The boundary is the facade actors talk to: the CLI, an HTTP client, a test. It adapts external protocols and carries cross-cutting concerns like mapping or authorization. Other BCs may call control directly; external actors never do.
3. Logic stays procedural. control holds stateless, function-like units. They are implementation details, trivially unit-testable and freely replaceable.
4. State has a home. entity holds the domain objects. They can be rich, carrying behavior next to their data, or anemic records passed between controls. Both are fine; what is fixed is where they live.

Dependencies flow in one direction: boundary calls control, control uses entity, never the reverse. And a BC only gets the layers its responsibility demands: lm.tokenization is a single control package, and that is fine.

See bce.design for the pattern rules. And yes, LLMs also like stability and predictability: airails.dev.

A feature request never arrives as "change all DTOs", it arrives as "implement support for NVIDIA Nemotron". Such a requirement lands in one main responsibility, with minor adjustments rippling into a few neighboring ones. Code organized by responsibility makes this visible: the package names tell you where the work happens and what gets touched as collateral. This is the idea behind the Business Component (BC): a package named after a responsibility, not a technology.

lightmetal, a zero-dependency Java 25 CLI application for GPU LLM inference on Apple Silicon, is structured this way. Every direct child of the lm package is a BC:

lm
├── catalog
├── configuration
├── generation
├── prompting
├── sampling
└── tokenization

Reading the package names tells you what the application does. No services, no utils, no helpers.

Inside, every BC follows the same convention from the BCE (Boundary-Control-Entity) pattern: up to three layers named boundary, control, and entity. The pattern goes back to Ivar Jacobson's use-case-driven OOSE from 1992, and the layer names have stayed stable for over three decades, while the industry cycled through DAOs, DTOs, Managers, Services, and Repositories.

See bce.design for the pattern and sbce.dev for the spec-driven workflow built on it.

TLDR: a static site splits into business components (BCs), each a directory exposing an index.html built with semantic markup and web standards only.

The BCE pattern is usually explained with Java: JAX-RS resources as boundaries, stateless logic as controls, Records or JPA entities. A static website has no code at all, and the mapping still works.

A static site built using only semantic HTML and modern CSS, with no JavaScript or build system, can be easily broken down into the three BCE layers:

1. Boundary: semantic HTML pages. The entry points for all external actors: users, crawlers, assistive technology. Landmarks, heading hierarchy, labeled forms, skip links. Exactly what a boundary does: expose the component to the outside world in coarse-grained operations. Here the operation is a page view.
2. Control: CSS-only interactivity. Behavior without scripts: details/summary accordions, :target modals, :checked tabs and hamburger menus, :hover + :focus-within dropdowns. State lives in native HTML elements, transitions are pure CSS. Stateless, declarative logic: a control layer with zero failure modes.
3. Entity: content and design tokens. Custom properties on :root are the domain model of the design: colors, spacing, typography, radii. Page rules reference tokens, never raw values. The same discipline as entities owning the data and everything else referencing them.

The business component structure carries over too. Content areas become BC directories named after domain topics:

site/
├── index.html
├── css/style.css
├── workshops/
│   ├── index.html
│   └── checks.md
└── trainings/
    ├── index.html
    └── checks.md

The boundary, control, and entity folders inside each component are omitted for the sake of simplicity.

Each component ships its own checks.md: observable, browser-verifiable expectations per page. Verification happens from the outside, by driving a real browser against the rendered pages: the interaction rules of a system with no code.

BCE is about separating entry points, behavior, and data. Turns out that separation exists even when the whole application is files on a web server. The approach is also fully Spec-Driven Design compatible: each BC maps to a capability spec (sbce.space).

Details: bce.design/web-static.html

1. Spec-Driven Development (SDD) on top of the Boundary Control Entity (BCE) pattern
2. why decades-old, well-documented BCE (traced to Objectory, 1992) lets LLMs generate lean, idiomatic code
3. SBCE as a single ~180-line text-file skill with "new" and "apply" actions, no CLI, no binary dependencies
4. the spec is "done" when all tests are green
5. inversion of control: tech stacks (Java CLI, MicroProfile server, web components, web static) declare participation, SBCE knows nothing about them
6. a business component is a package in Java and a folder on the web
7. exclusive reliance on open, crawlable standards: MicroProfile, Jakarta EE, BCE, JSRs, JAX-RS, EARS requirement syntax from Rolls-Royce
8. token economy via convention over configuration: reported 30-80% savings vs generic spec-kit / OpenSpec
9. package-info.java as the only coupling to the SDD process, specs living in Javadoc rendered via JMarkDoc
10. traceability between EARS requirements and generated tests
11. live demo: a Quarkus MicroProfile "episodes" component generated with SBCE new + apply, producing records, JAX-RS resources, resource clients and integration/system tests with requirement markers
12. live demo: a web static airhacks.tv episodes site built with BCE and static pages
13. standards-based CSS with custom properties / design tokens and Google Baseline, served by a zero-dependency ~60-line Java 25 web server
14. answering an 8-year-old ECB question from 2018 (episode 48) live via an LLM
15. Time Machine: revisiting ECB/BCE, JSF status, JSON-B vs JSON-P (preferring JSON-P with LLMs), Kafka / CQRS / event-driven architecture, closing JDBC connections back to the pool, and Light4J still going strong after ~10 years
16. where to put exceptions, repositories and utility classes in BCE: inside the owning business component, JAX-RS WebApplicationException subclasses, a project-wide "faults" package only if genuinely needed
17. BCE scales horizontally as a flat list of business components
18. BCE works with other languages, but LLMs generate Java more reliably (Tencent study)
19. keeping command line Maven as source of truth and upgrading the VS Code Java runtime to Java 25
20. CQRS / event-driven use cases: Kafka streams from wearables, DynamoDB streams and materialized views
21. a minimal event-listening router as a Vaadin Router replacement
22. local inference with Light Metal (Llama.cpp + Java 25, zero dependencies) running Nemotron and Gemma, with "lm list/prompt/serve" exposing OpenAI/Anthropic-compatible APIs
23. zsmith: a pure Java 25 agent framework with virtual-thread sub-agents and JFR events (viewable in JProfiler or JDK Mission Control), connecting to Claude, OpenAI, Bedrock and Light Metal
24. LLM-assisted legacy migration to Java 25 using SDD, OpenRewrite and BCE
25. skills downloadable as a zip, installed via a Java 25 script, no Node.js required

Ask questions during the show via twitter mentioning me: https://twitter.com/AdamBien (@AdamBien),using the hashtag: #airhacks or built-in chat at: airhacks.tv. You can join the Q&A session live each first Monday of month, 8 P.M at airhacks.tv

1. airhacks.tv became a YouTube show
2. Spec-Driven ("space" SBCE) BCE Demo
3. VS Code Java tooling issues
4. JMarkDoc announcement
5. LightMetal and zsmith news
6. BCE for ...static pages
7. Time machine: 100 episodes back (48th episode):

   JSON-B serialisation and deserialization, Automating Jenkins CI with Groovy, light4j, embedded SQL, CQRS streams and Java EE, 40k rows with JSF, Logging and debugging nasty libraries, Monitoring EJB transactions, JMS queue monitoring, REST authentication, Marshal and unmarshal JAX-B objects, ECB pattern in larger applications, Is JSF deprecated, Migrating Java EE projects, DataSource within Java EE: how to close a JDBC connection?

Any questions left? Ask now: gist.github.com/AdamBien/3a3090b3f6a6c1a686cdc8ca8a54d367 and get the answers at the next airhacks.tv. Some questions are also answered with a short video: 60 seconds or less with Java

See you at: youtube.com/bienadam/live

Subscribe to airhacks.fm podcast via: spotify| iTunes

SBCE (say "space"), short for Spec-Driven BCE, is a workflow: every capability is declared as a single spec, and the spec is the boundary contract (package-info.java or package-info.md for Web Components) of exactly one Boundary-Control-Entity business component (e.g. one Java package) with the same name. It ships as a AIrails skill: /sbce. No CLI, no dependencies.

BCE (skill: /bce) sets the architecture invariants: boundary/control/entity layering, package structure, naming rules. /sbce owns the workflow on top: declare a capability, then iterate on the code until it matches. SBCE provides the spec, BCE places the code, and a tech stack skill (java-cli-app, microprofile-server, web-components, web-static) adds code idioms and verification.

The spec lives in the BC's package doc: package-info.java as Markdown JavaDoc (JEP 467), co-located with the code it governs. No separate specs/ tree. The spec is just a better version of the JavaDoc a developer had to write anyway:

greetings
package-info.java   the spec: boundary ops + EARS requirements
boundary/           one method per declared operation
control/            implementation -- no spec section
entity/             maps to ## Entities

For a greetings BC, the entire spec is the package-info.java:

/// # Greetings
/// > Return a personalised greeting for a name.
///
/// ## Boundary
/// - `greet-visitor` — return a greeting for a name
///
/// ## Requirements
/// ### R1: Greet a visitor
/// - R1.1 — When a name is submitted, the BC shall return a
///   greeting containing that name.
/// - R1.2 — If the name is blank, then the BC shall reject
///   the request.
///
/// ## Out of scope
package airhacks.reception.greetings;

Everything in the spec is what, never how: the operation is verb-noun and transport-neutral (greet-visitor, not GET /greetings), and there is no frontmatter, because the BC name comes from the package. greet-visitor becomes the boundary's public method; each statement id (R1.1, R1.2) is stable and traces to at least one test that embeds it; the optional ## Entities section is simply omitted, because this BC owns no stateful domain nouns. Anything in the code without a spec counterpart is drift.

Every notation in SBCE is a stable, public standard: EARS for requirements, JavaDoc and package-info.java for placement, JEP 467 for the syntax, Mermaid for the generated BC map, and the decades-old Boundary-Control-Entity pattern itself. All of it is already in the LLM weights, so the skill never has to teach it: the complete workflow fits in roughly 4,000 tokens of SKILL.md. A self-invented spec DSL would burn thousands of extra tokens in every session.

Two modes drive the lifecycle:

/sbce new greetings         declare: author the spec, scaffold the layers
/sbce new "greet visitors"  declare from free text (github issue, Jira ticket): carves one or several BCs, new or existing
/sbce apply greetings       converge: close the spec-code gap, run tests until green

new loops clarifying questions until no boundary operation or EARS requirement has to be guessed. apply reads the gap in both directions: missing methods and tests are generated from the spec; undeclared methods or orphan trace ids are surfaced as drift, never silently absorbed. "Done" is a green run of the stack's own test loop, never the model's opinion.

/bce tells the code where to live; /sbce tells it what to promise.

jmarkdoc is a JavaDoc doclet that generates Markdown API documentation from Java sources and comments, ready for RAG pipelines, developer portals, and AI agents.

In Spec-Driven BCE: SBCE (say "space"), jmarkdoc generates the Markdown capability specs from package-info.java files, keeping the spec and the code in a single source. It requires Java 25, relies only on the jdk.javadoc and jdk.compiler modules, supports Markdown JavaDoc comments (JEP 467), adds nine contract tags for preconditions, postconditions, thread-safety, and idempotency, and links methods to EARS requirement IDs.