Bossmode

This page documents the way I actually run Claude Code. Which skills I have installed. Which agents do which work. How my folders are arranged. The small rituals that keep the system honest.

It is not a sales pitch and not a tutorial. It is a working document, the same way an engineer's notes file or a kitchen's prep list is a working document. My audience is anyone who reads code fluently but does not write it line-by-line, and anyone curious how a designer leans on AI in production without surrendering the design seat.

Most of what I ship lives in code. I don't think of myself as an engineer though. I think of myself as a designer who got tired of waiting for one.

Every link on this page goes to a real public source. Skills are MIT or Apache. The Boss skill is custom and small enough to copy. Take what is useful, replace what is not.

Vibecoding does not work on a model alone. Eight things have to be in place. The numbers in pink show how many of each I actually run today.

Without a front door, every conversation starts from zero. Preferences get re-explained, files get re-pointed-at, and quality degrades past message 30. 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 dispatches the right specialist or subagent. The result is that a three-word opener gets a system that is 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 spec mirror is at vibing-workflow/boss.md; the active skill at ~/.claude/skills/boss/SKILL.md. They stay in sync by hand. To start from this version, ask me for the file.

A skill is a markdown file with frontmatter that tells the model when to use it and what to do. Three sources: custom (drop-in at ~/.claude/skills/, no marketplace needed), plugin (installed from a marketplace), or bundled (ships with Claude Code, no install needed). Skills do not produce side effects on their own. They are the knowledge Boss leans on while routing or while doing 1–2 step work himself.

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.

Other MCP servers (PDF viewer, scheduled-tasks, MCP registry, session management) ship invisibly with Claude Code or via plugins. They exist but rarely need a direct mention.

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; it does the work without polluting the main thread; it returns a single summary. Five ship with Claude Code, two come from plugins. None are custom. Yet.

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
├── decisions.mddated changelog of workflow decisions
├── findings.mdtools evaluated, why kept or skipped
└── 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/
├── skills/drop-in markdown skills, project-agnostic
│   ├── boss/the custom orchestrator
│   └── impeccable/the design fluency layer
├── plugins/installed plugin cache
├── projects/.../memory/per-project auto-memory (feedback rules)
└── 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 auto-memory; 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 preferences to auto-memory. Then I clear; Boss reads state on the way back in and resumes without losing the thread.

Underneath the soft rituals there is a hard layer: hooks and permission rules. 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 SessionStart, PreToolUse, PostToolUse, Stop, and friends 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.

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

Two candidates queued, neither shipped:

• Em-dash check on index.html. The hard ban already exists in principles. A PostToolUse hook can grep the diff for the character and fail with a message. Catches the violation before it reaches the file.
• 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.

Both 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.

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 "ja" 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.
• Auto-memory feedback_*.md in ~/.claude/projects/.../memory/ · the silent preferences Boss enforces. If the page claims "no em dashes" but Boss keeps using them, an old memory rule probably says the opposite.

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.

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.

This page was built off a StyleProbe scan of impeccable.style, applied to a docs structure. A free scan is available. Email me for one. The full tool is paid.