madcompany

Workflows

Each project picks one mode. It decides what you plan with, what the team delivers in, and what each delivery is for. Set it with npx madcompany init --mode <mode> and switch any time with npx madcompany mode <mode>.

Release by release

UI-driven

Apps where the screens are the product: consumer and business apps, dashboards, mobile apps.

First release: Clickable prototype

init --mode uiRelease by release

MVP-driven

Products without much UI (APIs, CLIs, bots, data pipelines, agents), or when you want the smallest working thing first.

First release: MVP

init --mode mvpRelease by release

UI-MVP

Most new apps: a real, usable first version with a designed UI, as early as possible.

First release: MVP screens

init --mode ui-mvpRelease by release

Brownfield

An existing codebase: new features, fixes and refactors on an app that already runs.

First release: Onboarding

init --mode brownfieldEpic by epic

Spec-driven

Large or regulated products where the requirements are written down first and traceability matters.

Delivers: one epic at a time, approved at its demo

init --mode spec

Which one?

If… Use
It's a new app and you want a real, usable first version with a designed UI, fast UI-MVP
The screens are the product, and you want to see and shape the whole UI before any logic UI-driven
There's little or no UI: an API, CLI, bot, data pipeline or agent MVP-driven
The app already exists and you want features, fixes or refactors Brownfield
The product is large or regulated, and requirements must be written and traced first Spec-driven

Side by side

UI-driven MVP-driven UI-MVP Brownfield Spec-driven
Delivers in Releases Releases Releases Releases Epics
You plan with Brief + UX Brief + MVP scope Brief + MVP scope + UX for those screens A codebase scan Brief, PRD, UX, architecture, epics and stories
First delivery Clickable prototype of every key screen The thinnest slice that works end to end The MVP screens, clickable Onboarding + a first small change Epic 1
UI sprint with you Yes, first Only if you ask for screens Yes, for MVP screens When the change is visible Per epic with screens
You see it through Preview (web, Expo Go) Swagger UI or a CLI run Preview Preview or API explorer Preview, epic demo
Main planning skill /mc-plan-release /mc-plan-release /mc-plan-release /mc-scan, then /mc-plan-release /mc-plan-epic

Releases, not epics

In the four release-based modes the team works in releases: R1, R2, R3… Each has one goal written as something you can see or do when it's finished ("click through sign-up and the task list on my phone"), not a list of tasks. That keeps every release demonstrable, and your feedback on one shapes the next.

A release goes through five states. Two of them are yours:

Planned→Building→Your review→Approved→Shipped
  1. Planned. The lead proposes one release in one message (/mc-plan-release) and you confirm it. Tickets are created in it, and anything only you can do is filed in Human help straight away, so you can do it while the team builds on mocks.
  2. Building. Agents take tickets in their domain. Each ticket is reviewed by someone other than its author, then merged into release/rN by a queue that re-runs your checks.
  3. Your review. When every ticket is merged, the lead sends it for review. HQ → Releases shows it with Approve and Request changes. Changes go back to the team as a ticket in the same release.
  4. Approved. The lead runs npx madcompany ship R1: it merges release/r1 into main in your checkout, re-runs the checks if main moved, tags it (its version, like v0.1.0, or r1) and writes release notes.
  5. Shipped. Pushing and deploying stay yours: ship files them as a Human help item with the exact commands, plus your own deploy steps from deploy: in team.yaml.

Then the lead plans the next release with you.

Spec-driven projects follow the same flow with epics (E1, epic/1, HQ → Epics).

What stays the same in every mode