LiteSpec

Intent#

LiteSpec coordinates software work with agents as active engineering participants. It combines records, architecture standards, agent protocols, implementation conventions, tests, operating controls, and release records.

The name has two parts:

• Lite means a consumer adopts one bounded context, one size, and its selected stacks, and nothing more.
• Spec means approved written records and provisions define the work. Agents and people build and verify against them.

Company context#

Litenova Solutions authors LiteSpec and uses it as its engineering system for developing software. The system is general enough for another technical team to adopt. Litenova's company context defines the current defaults and explains the decisions in this repository.

One technical founder currently operates Litenova Solutions. LiteSpec assumes technical contributors. One person may hold product, domain, architecture, implementation, testing, release, and operations responsibilities at the same time.

The system names responsibilities without assuming separate departments or job titles. Decision owner, implementation owner, and operations owner identify accountability. They may identify the same person.

AI agents perform a substantial part of engineering work. They can inspect repositories, propose designs, edit authorized artifacts, run tools, and collect evidence. They do not own unresolved product policy, legal judgment, financial decisions, or risk acceptance.

Agent-led execution increases the need for explicit technical concepts. Agents distinguish modules from business records and journeys from event reactions. They also distinguish approved records from implementation claims.

Why the system exists#

Without a shared engineering system, two capable contributors or agents can implement the same request with different boundaries, names, transaction behavior, and verification. Each local result may compile while the workspace loses a coherent model.

The system addresses recurring problems:

• Product intent can be lost between a request and its implementation.
• Agents can invent missing rules when a record leaves a decision implicit.
• Standard technical concepts can be renamed until developers no longer recognize the established pattern.
• A use case can be implemented in one layer while persistence, public entry points, tests, or operating impact remain incomplete.
• Documentation can claim behavior that code and automated evidence do not support.

The system makes the record durable and the agent replaceable. A different person, model, or tool should continue from the same approved records and obtain the same required boundaries.

Connected layers#

The system contains one delivery approach and one operating model:

Driven means engineering work starts from an approved record and completion is judged against it. A record is more than a prompt because it remains in the workspace after one agent session ends.

Agent-driven describes who performs much of the execution. It does not transfer business decision authority to the agent.

Concepts#

The system uses related concepts rather than one hierarchy:

Product
  defines scope, outcomes, and operating constraints

Domain
  contains the business language, rules, state, and behavior

Module
  groups related language, use cases, business records, and code

Journey
  connects use cases to one observable product outcome
  can appear in a release record

Use Case
  defines one independently testable Command or Query goal

Business Record
  protects facts and rules changed in one step

Event
  records a completed fact

Event Reaction
  defines behavior caused by an Event

Result
  defines one way a Use Case ends

Case
  defines one working example of a Use Case

Acceptance Test
  proves one or more Cases

Journey Test
  proves one complete Journey through public boundaries

The central relationships are:

Product outcome
  Journey
    Use Cases
      Results
      Cases
      Acceptance Tests
    Journey Tests

Domain
  Modules
    Use Cases
    Business Records
      Business States
      Rules
  Rules

Command
  normally changes one Business Record

Query
  reads a Read Model

The glossary defines each term below. This section records the relationships and distinctions that a one-sentence definition cannot carry.

Product and journey#

The product record (the brief) names users, problems, outcomes, exclusions, commercial constraints, and operating context. It is not a synonym for the frontend application.

A journey begins at an accepted starting condition, crosses every required system boundary, and ends at one observable product outcome. It does not mean every possible product feature. The record lists ordered steps with what must exist first. It may include actor decisions, branches, waiting periods, failures, and recovery.

A journey links existing use-case records instead of repeating their inputs and rules. For an online shop, journey/checkout can connect stock reservation, order creation, payment start, and shipment dispatch. Order cancellation and payment reconciliation are separate journeys.

Domain and module#

Orders, refunds, shipment delivery, money, and cancellation policy are domain concepts. HTTP, JSON serialization, database sessions, and queue clients are technical mechanisms.

The capitalized Domain project is the code layer that implements domain types and behavior. The business domain exists independently of that project. Domain or Application code may enforce a rule across business records when its facts cross record or module boundaries.

Orders module is natural in product discussion and maps to Domain/Orders, Application/Orders, endpoint groups, frontend features, and tests. A module is not automatically:

• An assembly or deployment unit.
• A transaction boundary.
• One business record.
• A runtime base type or interface.

A module may contain no business record, one business record, or multiple related business records. Independent language, responsibility, or change reasons indicate separate modules. A use case belongs to the business record whose folder holds its page.

Use case, Command, and Query#

A use case owns its trigger, input, permissions, result, rules, refusals, entry points, implementation impact, and operating impact.

One top-level Command owns one command pipeline and one transaction commit. A Query reads a Read model without changing business state.

use-case/orders.cancel-order is a use case. CancelOrderCommand is its Application message. OrderCancel is its business-record action. These names stay aligned without treating the use case, Command, and business record as one boundary.

Work that spans business records is a Command that reads several records and writes one, an event reaction, or a background job. A background job is work that runs without an HTTP request, on a schedule or from a queue.

Business record, root, state, and rule#

A business record is not every entity in a module. Root identifies the mutation entry point, not an inheritance hierarchy for every domain object.

Developers may call it an aggregate. The record type is business record. Every business record uses one abstract {Record}State record and one or more sealed state records, including a record with one current state.

A rule that is always true cannot be false after commit. rule/order.capacity-limits-confirmation, for example, limits confirmed and reserved quantities to capacity.

Rules and permissions#

Each rule states its kind: always true, checked before, or across records. The kind decides how the rule is proved.

Checked-before rules include message shape: required fields, lengths, and formats are checked before business behavior runs. A persistence constraint is an always-true rule enforced by the store, such as a unique key. Each rule also states where it is enforced: validator, aggregate, store, guard, or reaction.

An actor holds a role at a scope. A role allows permissions. A use case needs permissions. An entry point may offer fewer. Actor kinds are person, company, provider, system, and guest. A role scope is a kebab-case level the project names, such as platform, tenant, or self. Permissions come from one shared closed list.

Event and event reaction#

Event names use past-tense forms such as OrderConfirmed and ShipmentDispatched. Reaction states the causal relationship without prescribing the implementation.

A reaction may map to an event handler, a projection, a Command that reads several records, or a background job. OrderConfirmed may cause the reaction Dispatch shipment, implemented as a background job rather than a class named DispatchShipmentReaction.

Each reaction declares one delivery classification:

• atomic: the reaction completes in the same transaction as the event.
• durable: the reaction is recorded beside the event and runs after the commit, retrying until it succeeds.
• rebuildable: a missed delivery is recovered by rebuilding the effect from its source records.
• best-effort-optional: the reaction may be skipped or lost without breaking a promise.

Select atomic for a required effect inside one consistency boundary. Select durable for one outside it. Select rebuildable for a derived view. Select best-effort-optional only where no record needs the effect.

Result, Case, and verification#

A result names one way a use case ends: success, or a named refusal with its failure code. A case pairs one situation with the result it leads to.

An acceptance test proves a case only when its steps call the use case and assert the result. Acceptance tests prove use-case behavior. Journey tests prove that connected use cases produce the release outcome.

Authority and links#

What should happen follows constraint, product, requirement, rule, then use case. A decision explains a choice. It is replaced, never edited. Research, examples, and prose carry no authority.

What is true today comes from code, screens, and test runs. A mismatch between the two is a defect, assigned to the owner of the higher record. A failing test does not settle intent.

When two records at one level disagree, the one whose decision was approved later wins. Otherwise, their shared owner decides.

Written links live on the record named first: a decision decides a requirement, a rule fulfills one, a use case raises an event. The model builder computes implements, calls, and proves from code, routes, and test runs.

Record catalog#

Every record has an owner and a status: draft, approved, or retired. A draft has a decider and a decide-by date.

Entry points#

People and systems reach the product through entry points. An entry point is a web app, a public API, a CLI, an MCP server, a site, a reaction, or a job.

The model builder computes which screens call which use case from routes and generated clients.

Scenario and reference cast#

A scenario is one concrete occasion for the subject of a record: who acts, what surrounds them, and what they would do instead. It answers when the behavior happens, which no rule, state, or mapping table states.

A reference cast is the one record every scenario draws its people, place, dates, and amounts from. Independent scenarios invent a merchant and a customer for each page, so nothing carries between two pages read in sequence.

Both are informative. A scenario illustrates its page and never governs it. A scenario that disagrees with the page it sits on is the part that is wrong.

Standards#

{
  "type": "journey",
  "id": "journey/borrow-and-return",
  "title": "Borrow and return",
  "owner": "lending-team",
  "status": "approved",
  "actor": "actor/reader",
  "goal": "Borrow and return a copy.",
  "steps": [
    { "useCase": "use-case/lending.register-copy", "actor": "actor/reader", "requires": [] },
    { "useCase": "use-case/lending.borrow-copy", "actor": "actor/reader", "requires": [] },
    { "useCase": "use-case/lending.extend-loan", "actor": "actor/reader", "requires": [] }
  ]
}

Use case: use-case/orders.cancel-order
Command:  CancelOrderCommand
Result:   result/cancel-order.order-canceled
Case:     case/cancel-order.canceling-twice-is-refused
Event:    event/order.canceled
Endpoint: CancelOrderEndpoint

"reachedThrough": ["entry-point/webshop"]

Conventions#

docs/
  product/
    README.md
    brief.md
    business/
      pricing.md
    markets/
      expansion.md
    roadmap/
      milestones.md
    decisions/
      0047-guest-checkout.md
    problems/
      abandoned-carts-lose-sales.md
    features/
      guest-checkout.md
    journeys/
      check-out-as-a-guest.md
    constraints/
      payment-card-rules.md
  domain/
    README.md


    actors/
      buyer.md
    roles/
      shop-manager.md
    permissions.md
    entry-points.md
    rules/
      pricing-rules.md
    modules/
      README.md
      orders/
        README.md
        orders/
          README.md
          cancel-order.md
  research/
    address-lookup-providers.md
  operations/
    limits.md
    secrets.json
    log/
  runbooks/
    restore-a-backup.md
  exceptions/
    temporary-direct-database-read.md
  known-gaps/
    checkout-cases-unproved.md
  ui/
    README.md

  language.json

Reference example#

This informative example demonstrates litespec/core/system#connect-one-product-outcome-through-a-journey, litespec/core/system#declare-event-reaction-delivery, and litespec/core/system#make-business-record-ownership-explicit.

The journey/checkout journey links use-case/catalog.reserve-stock, use-case/orders.create-order, use-case/payments.start-payment, and use-case/shipping.dispatch-shipment. Order cancellation and payment reconciliation are separate journeys.

The orders module contains Order and OrderClaim. use-case/orders.cancel-order changes Order. It cites rule/order.cancel-only-before-shipment. use-case/orders.claim-guest-order changes OrderClaim. Their shared module name does not merge their transaction boundaries.

OrderConfirmed records a completed fact. Dispatch shipment is its event reaction, declared durable. The page does not name the class that runs it.

Verification#