macss

Both install to %LOCALAPPDATA%\macss or ~/.macss, add the directory to your PATH and create the ma alias.

Both scripts are worth a minute before you run them: install.ps1, install.sh.

An agent reasons best about a codebase with clear boundaries, predictable structure and explicit contracts. MACSS is those three things written down.

• Single-responsibility layers — each component has one job, so the agent knows where to look and what to change.
• A monorepo with a canonical structure — code, documentation and infrastructure live together, so the agent sees the whole picture in one repository.
• Closed-loop verification — automated checks validate every change, so the agent confirms its own work before the developer reviews it.

Every request crosses layers that each do one thing, and the separation is enforced rather than encouraged: the interface never touches the database, business logic never knows about HTTP, and persistence never formats a response.

Interface

Presents information and captures interactions. A UI, or a CLI.

Controller

Holds application state and orchestrates interface and services.

Service

The transport between client and server. Abstracts HTTP away.

API

Exposes endpoints and routes each request to a use case.

UseCase

Business logic. Typed input and output, validate() then execute().

Repository

Data access. Executes queries and commands.

DB

Persistence, managed as Database as Code — DDL scripts, no ORMs.

The api and app layers have an implementation: modular_api provides the use-case lifecycle, CQRS routing, generated OpenAPI, health and metrics on the server, and transport-agnostic REST and GraphQL clients for the presentation layer.

Every MACSS project is one repository, and exactly one line in it is rigid: code lives under code/, documentation under docs/. That separation is the canon. What goes inside code/ is the project’s own business.

project/
├── code/            → the canon ends here
├── docs/
│   ├── adr/          → architecture decision records
│   ├── architecture.md
│   └── roadmap.md
└── README.md

macss project create opens a project on four layers, because most software has them:

code/
├── db/    → SQL schemas, DDL scripts, repositories
├── api/   → use cases, endpoints, server
├── app/   → services, controllers, views
└── infra/ → CI, containers, environment config

They are an offer. macss project check never asks for them and does not object to what it finds instead — a CLI, a documentation site, a book, an editor extension. ADR 0011 says why: both projects meant to demonstrate the methodology broke the old rule in the same direction, and when that happens the rule is what is wrong.

Inside code/, business logic is organised as modules — vertical slices grouping the use cases of one domain:

code/api/modules/
├── clients/   → create, list, get, update, delete
├── billing/   → invoice, payment, refund
└── inventory/ → stock, transfer, adjustment

Each module declares its boundaries and its dependencies. One that needs to scale on its own can be extracted as a service without changing anything inside it.

It carries the delivery cycle end to end: it opens the requisition, adds the contract, publishes both to a GitHub issue, runs the stage gates, and takes the delivery and its evidence to a pull request.

Routes are one of two kinds. A query reads and answers. A command changes something and says what it would change first: every one takes --plan or --apply, and neither is the default.

macss project create --path <dir> --lang <en|es> --apply

Open a project on docs/, code/ and the four starter layers. Delete the ones that do not apply.

macss requisition new --apply <slug>

Open a requisition: the product owner’s form, its issue metadata, and the active pointer.

macss requisition publish --plan

Show what would reach GitHub — the exact gh line included — and change nothing.

macss dor check

Definition of Ready: the request, the contract, and a published issue.

macss delivery publish --apply

Push the branch and open the pull request from the delivery.

macss skill deploy --host <hosts> --scope <global|repo> --all --apply

Put the lifecycle skills where your AI coding host reads them — Claude Code, Codex, Antigravity, OpenCode, Copilot. list, remove, doctor and validate come with it.

macss skill doctor

What is deployed on this machine, which tool owns it, and what has changed since. Other tools deploy skills too; this says which are yours.

macss help

Every route this CLI accepts, listing what reads apart from what changes.