# SBCE (say "space")

> SBCE is spec-driven Boundary-Control-Entity development where the spec *is* the boundary package's own doc: one `package-info.java`, co-located with the code it governs and published as Javadoc. Code over markdown: no parallel `specs/` tree, no drift.

SBCE is an [airails.dev](https://airails.dev) skill: Markdown your agent reads, not a tool you install. It adds no CLI, no dependencies, and no installation, and it is one Markdown file (about 180 lines) you can read end-to-end before you trust it. One business component maps to one spec written in the boundary package's `package-info.java` ([JEP 467](https://openjdk.org/jeps/467) `///` Markdown). Requirements use [EARS](https://alistairmavin.com/ears/) with stable ids (`R1.2`) that bind bijectively to tests; "done" is a green test run, never a markdown checkbox.

Concerns that span components live one altitude up, in the base package's own `package-info.java`: cross-BC wiring, system invariants (stable ids `Sn`), and shared vocabulary. This system doc is optional (a one-BC project needs none) and still code, so there is still no `specs/` tree.

When Markdown is needed after all — for agents, RAG pipelines, or developer portals — [jmarkdoc](https://github.com/AdamBien/jmarkdoc), a zero-dependency `javadoc` doclet, generates it from the `package-info.java` specs and renders each `@requirement` id for traceability. Markdown becomes a build artifact generated from the spec, never a second source of truth.

The workflow is two modes:

- `/sbce new <bc-or-feature>` declares. Give it a feature in plain words (`"let a customer check out a cart"`) or a BC name (`checkout`). The forms differ by altitude: a feature is intent-level — domain language, no architecture presumed, drivable by a PM/BA or a dev — while a BC name is structure-level, for the dev who has already decided the carving. It loops clarifying questions until no boundary op or requirement must be guessed, decomposes a feature into one or more BCs you confirm, then writes the spec into each `package-info.java`.
- `/sbce apply <bc>` converges. It reads the gap between spec and code in both directions: `spec → code` adds a boundary method per op, a test per requirement id, and the code to pass them; `code → spec` surfaces any orphan method or test as drift. It loops the stack's own test suite until green. Idempotent: an in-sync, green BC is a no-op.

## Examples

- [zb](https://github.com/AdamBien/zb): Zero Dependencies Builder — a lightweight Java build tool built with SBCE. Every business component (configuration, discovery, compiler, packer, …) declares its boundary ops and EARS requirements in its `package-info.java`, and each `Rn.m` id traces to a test.

## Feedback

> "I was absolutely fascinated by the simplicity and how much sense everything makes, and honestly, I'm a bit embarrassed that something like this never really crossed my mind. It just makes a perfect sense. P.S. I've been experimenting with it until the morning and I'm completely blown away by how efficient it is…" — [Mihailo Šibonjić on LinkedIn](https://www.linkedin.com/feed/update/urn:li:activity:7478090244689473537?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A7478090244689473537%2C7478108099107594240%29&replyUrn=urn%3Ali%3Acomment%3A%28activity%3A7478090244689473537%2C7478707811758305280%29&dashCommentUrn=urn%3Ali%3Afsd_comment%3A%287478108099107594240%2Curn%3Ali%3Aactivity%3A7478090244689473537%29&dashReplyUrn=urn%3Ali%3Afsd_comment%3A%287478707811758305280%2Curn%3Ali%3Aactivity%3A7478090244689473537%29)

## Documentation

- [SBCE site](https://sbce.space): Spec-driven BCE, the spec lives in your code.
- [Example prompts](https://github.com/AdamBien/airails/tree/main/bce/sbce#example-prompts): Usage examples in the skill's README.
- [/bce](https://bce.design): Boundary-Control-Entity architecture invariants, composed with SBCE.
- [jmarkdoc](https://github.com/AdamBien/jmarkdoc): A zero-dependency `javadoc` doclet that generates Markdown API docs from the `package-info.java` specs, with `@requirement` traceability.
- [airails.dev](https://airails.dev): The skill platform SBCE is published on.
- [airhacks.live](https://airhacks.live): Live workshops and sessions on clouds, web, Java, architecture, and agentic development.

## References

- [JEP 467](https://openjdk.org/jeps/467): Markdown Documentation Comments (`///`) used for the spec.
- [EARS](https://alistairmavin.com/ears/): Easy Approach to Requirements Syntax used for requirement statements.