Start — your first hour with BOSS

▸install

either one puts `boss` on your PATH

npm install -g oyeboss            # the usual — macOS, Linux, Windows
brew install ajeshh/boss/oyeboss  # macOS; then plain `brew install oyeboss` works
# then open the project in Claude Code — terminal, VS Code, Cursor or JetBrains, your call

or, already inside Claude Code: no npm at all

/plugin marketplace add ajeshh/bossbuild   # the repo is its own marketplace
/plugin install boss@bossbuild
/boss:welcome                             # the front door — asks what you're building, says it back, then offers to set it up

The plugin is deliberately thin: one skill and boss on Claude's PATH. Everything else (the mentors, the conscience, the skills) arrives in your project when you say go. It is not yet listed in Claude's plugin directory; the lines above add this repo directly, and that path is verified against the current release.

▸path A

Something new

Scaffold it

boss new my-app creates the project, git-inits it, registers it, and starts you in Quickstart with 4 agents and 15 skills.

Open Claude Code

cd my-app then claude, terminal or editor panel. First time? /welcome is about a minute, and it asks where you're starting from so the tone fits.

Point it at the idea

/boss <your idea>: a sentence, a doc, a Google Doc, an Obsidian note, a PDF, or a URL. It says the idea back in your words first (what it is, who it's for, the smallest version that proves it, and which way it read any word that could go two ways), then asks three things nobody else does: why this one, for you, what would “it worked” look like in three months, and if it works, what's here in a few years. Skip is an answer. Already written it down? /import <file|url>. Just want to see something move? /prototype builds the smallest clickable version to react to.

Come back later and run `boss status`

The one command worth remembering. After a few days away it tells you where you are and what's next.

▸path B

A repo you already started

Don't start over. cd into it and run boss adopt; it reads how far along you already are (a build manifest, source files, tests, CI, a deploy config), prints what it found, and starts you at the mode that matches.

Non-destructive throughout: your files are untouched, and an existing CLAUDE.md or AGENTS.md gets a marked block appended rather than replaced. It caps its own guess at MVP on purpose, because V1 is a design-system and database commitment, and that's your call, not a machine's. If it reads low, boss unlock <mode> is one command.

Then run /read-repo inside Claude. That's the adopted repo's version of /boss: BOSS reads the actual code, tailors the scaffold, and seeds the venture brain so the conscience starts with real context instead of guessing.

▸where you're starting from

It tunes itself to you

/welcome asks this once, in these words (four of its eight answers). It changes how much it explains and how the conscience frames a nudge, nothing else; the mode is yours.

this is the first thing you've built Stay in Quickstart a while. Capture ideas, pressure-test one, let the conscience teach you the rhythm. Don't rush to unlock; the next mode will still be there.

you've shipped a couple of small things Building feels possible; what's-worth-finishing less so. Capture freely with /idea; the payoff is /canvas. Unlock MVP when you're actually building, not before.

you've shipped real products before Skip the tour. Your value isn't the scaffolding; it's the conscience catching drift you'd rationalize, and the mentors for the parts that aren't engineering. Move fast through the unlocks.

being wrong has real costs Health, legal, money, safety. Same path, harm lens on early: the canvas's Risks & Harms cell taken seriously from day one; then, at MVP, /ai-failure-states as soon as your code first calls a model, and /red-team --humane before anyone relies on it.

▸the way out

Changed your mind?

boss remove previews exactly what would go; --apply does it. It only removes what BOSS wrote; your code, the ideas and decisions you captured, your own skills, and any BOSS file you edited all survive, and your CLAUDE.md keeps everything except BOSS's marked block. boss remove --global takes it off the machine instead; your projects keep working, since the conscience hook runs from the project, not the CLI.

And it hands back the thinking on the way out. If BOSS built up a venture brain about your project (what it understood, what it concluded) that gets exported to docs/venture-brain.md before anything is deleted. You wrote into it and you could edit it, so it leaves with you rather than with the tool.

A clean exit is what makes the entrance safe to try.