Bossmode

I am a designer, just as most of you I see how AI takes more ground every day. But I also have been using it since day one, following every move, tried (not all) a ton of tools, models, workflows. Doing so I have a better understanding about where it will take over and what my role could be when this transition is over. Because, let's be honest… we don't know where this is going. Nobody does.

So I try, fail, optimize, fail again. And now I share what works for me and how. Not to teach, but to bring my workflow out in the open so we (yes you and I) can talk it over, compare, make it better, learn and laugh about it when we look back in a couple of months.

I started just vibe-coding, expecting the model alone to do it. It doesn't. You run out of road fast and start burning hours and money looping around bug-fixes. So I tweaked. These eight things turned out to matter for me. The numbers in pink show how many of each I actually run today. MCP and hooks sit alongside, surface area, not foundation.

I kept re-explaining the same things every conversation. Files I'd already pointed at, preferences I'd already stated. Past message 30 or so, quality drops anyway. Boss is one markdown file at ~/.claude/skills/boss/SKILL.md that fires when the opener is vague ("Let's…", "What's next?", "Where do I start?"), reads the project state, takes a stance, and routes to the right specialist or subagent. A three-word opener now gets a system that's already three steps ahead.

What Boss does, in order

1. Reads the state. tasks.md for what is in flight, progress.md for the running journal, git log --oneline -10 for recent commits. Never reads everything; reads enough to take a stance.
2. Takes a stance. One sentence acknowledging where things stand. Not a summary, not a recap. A position.
3. Asks at most two questions. Short, snappy, in my voice. Skips questions when state already answers them.
4. Routes, doesn't do. Picks one of three paths: a specialist skill (impeccable for design polish, frontend-design for new UI, superpowers:systematic-debugging for bugs), a subagent (Explore, Plan, general-purpose), or a direct action when the work is one or two steps and obvious.
5. Applies house rules silently. Snappy three-part response shape, no padding, default to no comments in code, batch commits, never auto-push. Boss enforces the whole stack so a preference is never re-stated.

Boss lives only on my machine, but the markdown is small enough to copy. The public spec is at vibing-workflow/boss.md; the active skill at ~/.claude/skills/boss/SKILL.md. They stay in sync by hand.

Also available as a markdown file: download boss.md.

I guess skills are the next big AI buzzword after "AI" itself. You can download them by the hundreds, but don't be fooled, most of it is rubbish. Never, never install a whole pack from some hyped repo without knowing why you want it, and at minimum reading what each one does.

A skill is just a markdown file. The frontmatter at the top tells the model when to fire it. That's it. Three places they come from: custom (drop-in at ~/.claude/skills/, no marketplace needed), plugin (installed from a marketplace), or bundled (ships with Claude Code, no install). Skills don't do anything on their own; they need a tool to act. They're the knowledge Boss leans on when routing, or when he's handling 1–2 step work himself.

Two more plugins (code-simplifier, context7) sit in Subagents and MCP because that's their primary export, for seven plugins total.

MCPs are like a fine beer. Drink one or two and it feels like you gained something; drink more and that feeling turns into a costly headache. Yes, they extend the reach of your setup, but they're more token-thirsty than a cactus on Mars.

MCP (Model Context Protocol) servers are a different mechanism than skills. A skill teaches the model what and when; an MCP server gives it tools: a browser to drive, a desktop to click, a Figma file to write into. The model can't take any action that no tool exposes; MCP is how the surface area expands. They install via ~/.claude/settings.json or as part of a plugin's .mcp.json, not as markdown.

The five above are the workflow tier. Underneath sits a productivity tier (Notion, Linear, Atlassian for Jira and Confluence, Gmail, Google Calendar, browsermcp, Claude-in-Chrome, sequential-thinking, plus my own rogerroger MCP) and a plumbing tier that ships invisibly (PDF viewer, scheduled-tasks, MCP registry, session management). The productivity ones are real, opt-in installs; I just don't reach for them from the design/code loop this page describes, so they sit one section deeper than the five above.

A subagent doesn't exist until your main AI spins it up… destined for a short life: do task A, bring back the result, die. That's literally how it works. Where a skill is knowledge inside the main conversation, a subagent is a worker in its own context window. Boss hands one a self-contained prompt (spin up); it does the work without polluting the main thread (task A); it returns a single summary (bring back the result); then it's gone (die).

But they're not without character. You can give each one a name, a specialty, a workflow shape. They perform better that way, and your main agent (Boss, in my case) picks the best-suited one for the task at hand.

Five ship with Claude Code, two come from plugins. None are custom. Yet. Custom subagents drop in at ~/.claude/agents/<name>.md: same shape as a skill, but run in their own context window.

Suuuuper underestimated. Even a default setup gets a real bump from the right folder structure. I use it to stay consistent: when Claude Code (or whichever provider you use) knows where to find what it needs, it performs better.

vibing-workflow/ is this project: the page, the brand, the design system, plus a development/ subfolder with the active spec and journal. ~/.claude/ is global Claude Code config: skills, plugins, per-project memory. The same shape works for any project; copy it.

vibing-workflow/
├── README.mdhow to use this folder
├── index.htmlthis page
├── PRODUCT.mdbrand, audience, anti-references
├── DESIGN.mddesign system tokens
├── boss.mdspec mirror of the Boss skill
├── bootstrap.mdthree-stage flow for spinning up a new project
├── decisions.mddated changelog of workflow decisions
├── findings.mdtools evaluated, why kept or skipped
├── assets/page images (hero, etc.)
├── marketing/outward-facing snippets and cards
├── workflows/workflow spec drafts (/design-sprint, ...)
└── development/
    # always: Boss opens every session
    ├── tasks.mdin-flight, planned, recently done
    ├── progress.mdrunning journal
    ├── changelog.mdpublic release notes

    # on intent: Boss opens when topic matches
    ├── overview.mdwhat this project is
    ├── architecture.mdfile map, page section structure
    ├── principles.mdcode and design rules
    ├── context.mdbroader context for AI agents
    ├── permissions.mdwhat AI can do without asking
    ├── plan.mdlong-horizon roadmap

    # reference: source material, consulted during design work
    └── design-reference/scanned DESIGN.md inspirations

~/.claude/
├── CLAUDE.mduniversal rules, auto-loaded every session
├── skills/drop-in markdown skills, project-agnostic
│   ├── boss/the custom orchestrator
│   ├── impeccable/the design fluency layer
│   └── humanizer/the AI-pattern copy editor
├── plugins/installed plugin cache
├── projects/.../memory/per-project rules only (framework, language, quirks)
└── agent-flow/custom telemetry hook

The development/ folder has ten things in it; only three are always-load. The other six get read on intent match (architecture, overview, principles, context, permissions, plan), and one folder (design-reference/) is source material for design work. The three below have distinct jobs and never overlap.

Each one is codified in ~/.claude/CLAUDE.md; Boss enforces them silently. The reason matters as much as the rule.

When to commit · done, tested, passed

I commit when a feature or unit of work is finished, tested, and passing. Typecheck clean. Dev-server smoke tests OK. Relevant tests green. I also commit on my own explicit "ok" or for genuinely minor things: typo fixes, copy tweaks, dependency bumps that do not change behavior. Never on work-in-progress.

My git log should read as a series of "this thing now works" milestones, not a stream of save points.

When to push · batch, on explicit request

Commits are local; pushes are deliberate. Boss never auto-pushes after a commit. Only when I explicitly say "push", or at the end of a major chunk of work. Before any meaningful push I bump the version pill; package.json and the visible UI version stay in sync.

When to clear · halfway, every time

I clear or compact the conversation when context hits roughly fifty percent full. Past that threshold, output quality drops: reasoning gets sloppier, recall of earlier instructions weakens, my snappy response shape erodes. Before clearing, I make useful state durable: decisions to decisions.md, in-flight work to tasks.md, new universal rules to ~/.claude/CLAUDE.md or project-only rules to per-project memory. Then I clear; Boss reads state on the way back in and resumes without losing the thread.

claude --resume brings any past session back if you need to dig into history; claude -c continues the most recent one in the current directory. Clearing isn't terminal.

When to plan-mode · before any unfamiliar prompt

Hit Shift+Tab to enter Plan Mode before pasting anything you didn't write yourself: a copied install prompt, a fresh slash command from a marketplace, a workflow you haven't run before. In Plan Mode Claude proposes the steps and waits for explicit approval before writing, editing, or running shell. The cost is one extra round-trip; the upside is no blind execution against your filesystem.

Some rules are soft. I follow them, Claude follows them, but nothing stops you from forgetting. Some have to be hard. Hooks and permission rules are the hard ones. Both run inside the harness, before Claude sees the request. Both can prompt me with the standard three-button dialog (Allow once, Allow always, Deny) or block the action outright. Different mechanisms, same job: turn a rule from a soft preference into something the harness actually enforces.

Two mechanisms, one purpose

A hook is a shell command (or LLM prompt, or HTTP call, or MCP tool call) the harness runs at a lifecycle moment: session start, before or after any tool call, when Claude stops, on compaction. It receives the event payload as JSON, can log silently, modify the input, or block the action. Configured under hooks in ~/.claude/settings.json.

A permission rule is a declarative match: it pairs a tool name with a path or argument pattern and an action (allow, deny, ask). When Claude attempts the matching tool call, the harness applies the rule. Configured under permissions in the same file.

What I run today

Two pieces.

One observability hook on every event, dispatching every lifecycle event the harness emits (SessionStart, PreToolUse, PostToolUse, Stop, and the others) to agent-flow's tracker. Third-party, log-only, never blocks. Useful for understanding what an agent did across a session.

One ask rule on development/client/. Any Edit or Write by Claude on a path under development/client/** triggers the three-button prompt. Client material (briefings, brand assets, references, process notes) is read-only by default; I unlock it case by case when I actually want Claude to touch it.

Three settings scopes live in parallel files: ~/.claude/settings.json (user, personal preferences), .claude/settings.json at project root (committed, for team-shared hooks and permission rules), and .claude/settings.local.json at project root (gitignored, for personal overrides on this one project). Precedence is local > project > user. I run user-scope only because I work solo, but the three-tier shape is what makes this gate workable on a team.

Where they don't fit

A hook can't decide intent. It can match patterns and execute, but it can't read my message and judge whether to start a workflow or which skill to invoke. Boss-routing, the bootstrap conversation, the design-sprint pipeline. All LLM territory, all stays in skills. Hooks and permissions supplement the soft rules; they don't replace them.

Watching for

One candidate queued, not shipped:

• git push confirmation. A PreToolUse hook on Bash that blocks if the command contains git push and my recent input doesn't contain "push". Hardens the batch-push ritual into something the harness checks rather than something Claude has to remember.

Queued, not shipped, until the existing two pieces have a few weeks of real use.

The eighth foundation. A workflow is a slash command that runs a sequence of phases. Each phase calls an existing skill, writes a markdown artefact, and hands off to the next. Different layer than Boss-routing: Boss decides per message, a workflow commits to a fixed shape. Boss may suggest a workflow when intent matches; he never auto-starts one. Multi-phase commitment without consent is too expensive when wrong.

A slash command is just a markdown file. Drop my-thing.md into ~/.claude/commands/ (global) or <project>/.claude/commands/ (project-scoped) and /my-thing is available in any Claude Code session in scope. The file is the prompt; the filename is the command. /design-sprint lives at ~/.claude/commands/design-sprint.md.

The principle: codify only what you've already done three times by hand. One workflow is in build; the rest are queued until a real run earns them.

A workflow is two things together: a sequence and a set of artefacts. Drop either and you're just running skills back-to-back without state between them.

This is a permanent project on my Mac, not a static publication. The skills, plugins, MCP servers, and workflows above will keep changing. Every time I add or remove something, the same loop runs: vet for fit, decide where it sits, wire it into Boss, log the choice. Once a quarter I run the inverse: what has not been touched in 30 days, what can go without losing capability? Then I remove and log. Adding gets all the attention; pruning gets none, and that is wrong. The page you are reading should be readable as a snapshot of the current system, not a frozen artefact.

The drill · adding something new

When I find a skill, plugin, or workflow that looks useful, the loop is two prompts. Both copy-pastable, both before any install command runs.

Step 1 · Vet. Paste this with the repo URL filled in:

Can you tell me how this [LINK TO REPO] will affect our Boss setup? I want to know about overlap, conflicting slash commands, conflicting instructions.

Boss reads the new thing, reads the existing setup, and surfaces three checks:

1. Overlap. Does this duplicate a skill or workflow I already have? If 70%+ of its surface is covered, the answer is usually "don't install."
2. Slash-command collisions. Does it want a name I already use? Does it shadow an existing command from a plugin?
3. Conflicting instructions. Does it tell the model something opposite of my house rules: auto-push when I batch, em-dashes when I ban them, comments-by-default when I default to none?

Step 2 · Plan and wire. If the three checks pass, paste the second prompt:

If the vet is clean, write me a short plan: fit (where this sits in the process), routing (when Boss should reach for it), wiring (which files get updated: boss.md, ~/.claude/skills/boss/SKILL.md, the page, decisions.md). Wait for my confirmation before changing anything. After execution, log a dated entry in decisions.md: what changed, why, what to watch for.

Boss returns a three-part plan in that exact shape. I read it, say "yes" if it's right, and the wiring runs. The dated decisions.md entry is the trail future-me reads back.

Where to look when something feels off

The system has three durable surfaces for self-correction. None requires a search.

• boss.md · the routing cheat sheet. If Boss reaches for the wrong specialist, the rule is here. Edit it; the mirror at ~/.claude/skills/boss/SKILL.md updates with the same content.
• decisions.md · the dated journal of why each choice was made. Six weeks from now, you'll want to know why a thing was removed. This is where to look.
• ~/.claude/CLAUDE.md · the universal silent rules that apply across every project (response shape, commit cadence, batch pushes, clear-at-50, etc.). If the page claims one thing but Boss does another, an old line here probably says the opposite.
• Per-project memory at ~/.claude/projects/.../memory/ · the silent rules that apply only inside this project. Empty by default for a new project; entries appear when something project-specific surfaces (framework class names, language preference, project-only quirks).

The discipline · why the loop matters

Without a check-and-log discipline, the system becomes a museum. Three failure modes happen if you skip the loop:

• Drift. Plugins update, new skills appear, your taste changes. Three weeks in you're working with a setup nobody documented.
• Silent overlap. Two skills both claim the same domain; Boss picks the wrong one half the time and you can't figure out why.
• Lost rationale. You remove something and six weeks later add it back, having forgotten why you removed it.

The friction is the feature. If a new skill conflicts with three existing rules, you find out before installing, not three weeks later when a request goes sideways and the trail is cold.

Three of my own workflow files are aspirational scaffolding I haven't touched in weeks (plan.md, permissions.md, context.md). They survive the loop because they read on intent match. If they ever stop being read, they go. The page already exposes that hierarchy honestly in the Folder structure tree. Three tiers: always-load, on-intent, source material.

A workflow file that nobody reads is a stale comment in a codebase. Same fix.

If you want the whole stack: copy the prompt below, hit Shift+Tab in Claude Code (to enter Plan Mode) for safety, then paste. Claude will investigate your current setup first, propose a step-by-step plan that respects what you already have, and wait for your "yes" before installing anything.

The prompt structure (investigate → compare → plan → wait → execute) does the same thing even outside Plan Mode, so it's safe either way. Reason for the structure: most readers already have plugins, skills, or memory rules. Blind installs cause slash-command collisions, overwritten CLAUDE.md files, and overlapping hooks. So Claude looks before it leaps.

Also available as a markdown file: download install-prompt.md.

Google open-sourced DESIGN.md (April 2026), a spec for letting AI coding agents read a design system. I'm a big fan of standardisation, so cheers. That said, the DESIGN.md they promote, and the ones sprouting up around the web by people at every stage of AI enlightenment, miss out on a ton of valuable stuff. So what do you do in the age of vibe-coding when you're not satisfied with what's out there? Yes! Build it yourself. Haha.

Most AI design output is bland because the brief was bland. Before any UI work, I scan a reference site with StyleProbe, a tool I built that captures the design DNA of any URL: typography, color, motion, spacing, iconography. Output is a structured DESIGN.md file that hands the model taste instead of templates.

With all respect to the Google team, I'm not saying their spec is wrong. I just figured out there's more depth worth capturing. Here's where StyleProbe's DESIGN.md output diverges:

In plain English: Google's DESIGN.md is for telling an AI what your own brand looks like, before it builds anything. You write the rules upfront. StyleProbe runs the other way. Point it at any site you admire and it captures what's actually there. No insider knowledge needed. The output hands the AI taste it can copy from.

This page, for example, was built off a StyleProbe scan of impeccable.style, applied to a docs structure. StyleProbe isn't public yet, coming soon. And no, this page wasn't built in one take. Got me to 80% of where I wanted to be. Connect on LinkedIn and DM me if you'd like early access in the meantime.