1. The mental model: three systems, one stack
The whole setup reduces to three independent systems that compose. If you remember nothing else, remember this split - every skill below belongs to one of them.
How one piece of work ships
The mattpocock-skills plugin: sharpen the idea, spec it, split it into tickets, implement each one test-first, close with review. One flow, idea to shipped code.
Whether work splits across workers
/so plus the Solo MCP: a triage agent decides pass-through, "grill me first", or a multi-agent board with todos and scratchpads. Always explicit opt-in.
Where the "why" survives
Persistent memory files + Open Brain (semantic store). Decisions, corrections, and project state outlive any one conversation, whichever axis produced them.
The rule that keeps them from fighting: each altitude of work has exactly one owner. A tracker (if the repo has one) owns specs and tickets; Solo owns one agent's in-flight mechanics; memory records outcomes. Section 4 covers how a repo declares which applies.
2. Ground rules (the CLAUDE.md contract)
These load into every session. They are behavioral guardrails, not suggestions - when teaching someone the system, start here.
| Rule | What it means in practice |
|---|---|
| Measure, don't assume | Uncertain claims get flagged "this needs measurement" with a verification plan, not a confident guess. |
| ROI baseline | Every automation records the human baseline first: person-hours at $25/hr vs agent time + token cost, per action and at expected volume. Feeds the agent factory. |
| Plan before building | Plan mode for architectural or multi-file work. If something goes sideways mid-build: stop, re-plan. |
| Validate small | Test connections before building on them; small-scale run before the full run. |
| Delegate when it wins | Subagents for genuinely parallel or noisy work only. Handoffs are lossy; small-task parallelism is usually negative ROI. |
| Simplicity + surgical edits | Root causes over patches. Every changed line traces to the request. "Would a staff engineer approve this?" |
| Concise output | ~4-line answers, result first. The cap never applies to work products (specs, code, docs) or decision-changing facts (blockers, risks, unfinished scope). |
| Prove completion | Never mark a task complete without showing it works. Corrections get captured to Open Brain as learnings. |
Standing corrections
Durable fixes from past mistakes - the system is told these every session so it never re-learns them the hard way:
| Correction | Detail |
|---|---|
| "Sales reps" | Canonical Empower term. Never "Energy Advisors" (deprecated 2026-05-15). |
| Granola summaries | Action items are unreliable - pull the verbatim transcript before publishing any shareable meeting doc. |
| Brave browser | Default for scraping / CDP attach, not Chrome or Chromium. |
| Headless jobs | launchd claude -p jobs need --permission-mode dontAsk. |
| Doc reviews | Markdown reviews go through the Obsidian vault _Reviews/ folder; edits apply to the canonical source. |
python3 ~/.keys/keys.py (get / set / list / gen-mcp / gen-codex). Nothing is ever hardcoded, and MCP configs are regenerated from Keychain, never edited by hand.3. The dev cycle (vertical axis)
The main flow for any real build. Each step is a skill; each hands clean context to the next. Keep grill through tickets in one unbroken conversation, then give every /implement a fresh one.
/tdd internally, slice by slice.On-ramps that merge into the flow instead of starting at grill:
/diagnosing-bugs - hard or intermittent bugs. Reproduce red first, then hypothesize.
/triage - externally-raised issues and PRs, moved through a 5-state machine to an agent-ready brief.
/wayfinder - work too foggy or big for one session. Maps decision tickets, resolves them one at a time, then hands off to /to-spec.
/prototype - when a design question needs a runnable answer before committing. Single HTML file, kept on a prototype/<name> branch.
When to grill: whenever the done-condition isn't checkable as stated. Small enough for one session? Skip spec/tickets and go straight to /implement. Not sure which skill fits? /ask-matt is the router.
4. Boards and modes (horizontal axis)
/so is the opt-in switch for multi-agent work. It never guesses - a cheap triage subagent scores the task and returns one of three verdicts:
Pass-through
Questions, lookups, single-spot edits. Zero overhead - executes normally.
Needs grilling
A real build, but an undecided decision would change what gets built. Routes to a grill interview first.
Orchestrate
2+ of: parallelizable, long-running, trail-worthy, multi-specialty, boundary-spanning. Builds a Solo board: one todo per workstream, findings scratchpads, workers assigned.
House mode vs tracked mode
One file decides who owns spec-level work in a repo: docs/agents/issue-tracker.md at the project root.
| House mode (file absent) | Tracked mode (file present) | |
|---|---|---|
| Where | The normal case - all Desktop projects. | Repos that ran /setup-matt-pocock-skills. Real example: JobFlo-co/jobflo (Linear tracker, since 2026-08-05). |
| Spec work lives in | Solo todos + scratchpads. | The repo's own tracker. Read the file in full before creating anything. |
| Project context | CLAUDE.md + .claude/history.md per the /normalize standard. | Whatever the tracker doc says (jobflo: AGENTS.md is authoritative). |
| Solo's role | Owns the whole board. | Only one agent's in-flight mechanics beneath a ticket. Never mirror tracker tickets as Solo todos. |
JobFlo-co/empower-agents is Kalvin's build - we consume tools it ships, we never implement, commit, or push there. Mode is detected from the tracker file only, never from a git remote or a project's name.5. House skills catalog
46 custom skills at ~/.claude/skills/, most symlinked from the Obsidian vault. Invoke by typing /name, or just describe the job - well-described skills trigger themselves. Click any card for what it does, when to reach for it, and a real example prompt.
/soroute a task: solo board, grilling, or pass-through
WhatTriages a task via subagent, then either executes normally, sends you to a grill interview, or builds a Solo board (todos + scratchpads + parallel workers). Tracker-aware.
WhenYou explicitly want multi-agent orchestration or a visible work trail. Never fires on its own.
/wrapsession-end: commit, capture, log
WhatAuto-detects how heavy the session was, then commits code, captures learnings to Open Brain, and updates the project's .claude/history.md.
WhenEnd of any real working session. This is what keeps history.md trustworthy.
/normalizebring a folder up to house standard
WhatAudits or fixes a project folder against the workspace standard: CLAUDE.md/AGENTS.md, .claude/history.md, naming, output dirs. Check mode (read-only report) and apply mode (approval-gated).
WhenNew project folder, or a messy old one you're about to work in seriously.
/check-mcpshealth-check MCP servers
WhatPings every configured MCP server with a lightweight call, reports alive/dead.
WhenBefore high-stakes sessions, or when tools seem to be missing.
/model-releaseroll a new AI model through the stack
WhatWhen any provider ships or retires a model: researches what changed, audits every local surface referencing models, applies updates in cost-of-delay order, smoke-tests, records state.
WhenNew model announcement, deprecation email, or the monthly deadline sweep flags one.
/skill-creatorcreate, improve, benchmark skills
WhatBuilds new skills from scratch, optimizes existing ones, runs evals, and tunes descriptions so they trigger correctly.
WhenA workflow repeats often enough to be worth packaging, or a skill keeps mis-triggering.
/mcp-builderbuild high-quality MCP servers
WhatGuided construction of MCP servers (Python FastMCP or Node SDK) with well-designed tools.
WhenWrapping an external API so agents can use it - like the Scanifly and Permits connectors were built.
/webapp-testingPlaywright toolkit for local web apps
WhatDrives a browser against local apps: verify flows, capture screenshots, read console logs.
WhenConfirming frontend changes actually work, debugging UI behavior.
/cbcommand bridge - the agent office router
WhatEntry point for the "5+3 agent office" - loads project context and routes work to the right agents.
WhenStarting structured multi-agent work inside an office-enabled project.
/design-handoffprototype to structured Linear project
WhatTurns a vibed prototype into a structured Linear project: docs, phased issues, dependencies.
WhenA prototype proved the idea and the build should become tracked, plannable work.
/kanbanCommand Center kanban board
WhatViews and moves tasks on the Command Center kanban, triggers Obsidian sync.
WhenManaging the personal task board without opening the app.
/linear-pmLinear project management assistant
WhatIssue creation, backlog triage, and status reports against Linear.
WhenPM chores on any Linear workspace you own.
/project-kickoffstandardized project lifecycle
WhatScaffolds, tracks, and completes projects with a consistent lifecycle.
WhenStarting a net-new project that deserves proper structure from day one.
/cscommercial solar project management
WhatCreates commercial project folders from intake data, evaluates go/no-go criteria, checks status, generates Jobflo reports.
WhenAny commercial solar intake, approval/denial call, or pipeline report.
/resiresidential solar customers
WhatManages residential customers: folder from template, branded HTML deliverables (problem page, solution page, summary page), pipeline tracking.
WhenAnything in Solar Sales/Residential - a new customer, a PPA page, an energy-cost analysis.
/utilityapipull authorized utility usage data
WhatFinds a customer's UtilityAPI authorization and pulls bills + interval usage as normalized CSVs into the project folder. Read-only.
WhenStarting usage or financial analysis for any customer who authorized data sharing.
/dialpadcustomer call and SMS history
WhatPulls a customer's Dialpad call and SMS history by phone number. Read-only.
WhenReconstructing what was said to a customer, or checking contact history before an escalation.
/podiummessaging, reviews, guarded SMS send
WhatPulls Podium conversations (SMS/webchat/social), reviews, and team stats. Can send a text - but only after showing the exact message + recipient and getting explicit approval.
When"Did they text us?", review summaries, or sending a customer message through the official channel.
/sop-architectbrain dump to standardized SOP
WhatTransforms rough notes, transcripts, or outdated docs into SIPOC-format SOPs in Empower wiki style, with versioning and role ownership.
WhenDocumenting any verbal process, or refreshing a stale SOP.
/monthly-reportbranded monthly accomplishments doc
WhatBuilds the Empower-branded monthly accomplishments Word doc from meeting notes.
WhenEnd of month, before the systems report is due.
/empower-sales-chartsbranded sales visualizations
WhatChart.js visualizations in Empower brand style for sales data.
WhenAny chart going into a deck or doc that leadership will see.
/pto-design-correctionsPTO corrections worklist report
WhatGenerates the "PTO Design Corrections" HTML worklist report.
WhenThe recurring corrections review cycle.
/brain-capturesave a thought to Open Brain
WhatCaptures thoughts/decisions/learnings to Open Brain with taxonomy-aware project routing (the whitelist in ~/.brain/taxonomy.json).
When"Capture this", "remember this", any decision worth finding again in six months.
/sunday-reviewthe weekly brain review interview
WhatConversational weekly interview compressing the week into durable knowledge, graph links, strategy, and a one-outcome plan.
WhenSundays. Says so in the name.
/morning-briefingdaily unified briefing
WhatOne briefing across calendar, email, Slack, and tasks.
WhenStart of the workday.
/meeting-syncGranola meetings into Obsidian + brain
WhatPulls Granola meeting notes via API, writes per-meeting Obsidian files with summaries and action items, appends to the daily note, captures to Open Brain.
WhenEnd of a meeting-heavy day, or catching up after travel.
/meetingprocess one recording or transcript
WhatUnified meeting processing - audio transcription or raw text into structured Obsidian notes.
WhenA one-off recording or pasted transcript that Granola didn't catch.
/emailGmail across both accounts
WhatGmail with strict work/personal separation (@work = Empower, @personal = gmail).
WhenReading, searching, or drafting mail without leaving the terminal.
/slackread, search, post
WhatSlack integration - unreads, channel history, search, posting.
WhenCatching up on channels or posting a summary.
/calendarGoogle Calendar + meeting prep
WhatEvents, availability, and meeting preparation from Google Calendar.
WhenScheduling questions or pre-meeting context pulls.
/drive-triageGoogle Drive filing
WhatTriage and file Google Drive contents - quick check or full classify.
WhenThe Drive inbox folder has piled up.
/panning-for-goldmine a transcript for actionable threads
WhatMines a transcript or brain dump for actionable threads and captures the verdicts to Open Brain.
WhenA long rambly recording probably contains three real ideas.
/memory-synthesisweekly session-log synthesis
WhatSynthesizes captured session logs into structured knowledge on a weekly cadence.
WhenPart of the weekly maintenance routine.
/brain-syncskills to Open Brain
WhatSyncs skill definitions into Open Brain so claude.ai/ChatGPT/Grok sessions can discover them.
WhenAfter adding or changing skills; also runs on the Sunday schedule.
/vault-maintenanceObsidian vault health
WhatVault health check and cleanup (orphans, naming, structure), quick or full, delegating to scanner subagents.
WhenMonthly, or when the vault starts feeling untrustworthy.
/docxWord documents
WhatCreate, read, and edit .docx - TOCs, headings, letterheads, tracked changes, find-and-replace.
WhenAny deliverable that must land as a Word file.
/pdfPDF everything
WhatRead, extract, merge, split, rotate, watermark, form-fill, and OCR PDFs.
WhenAny .pdf in or out.
/gwsGoogle Workspace CLI toolkit
WhatTasks, Docs, Sheets, Drive, Chat, Meet - the whole Workspace surface from the CLI.
WhenReading or writing Workspace content programmatically.
/researchFabric AI - videos and articles
WhatRapid research via Fabric AI patterns: process YouTube videos and articles, extract wisdom, summarize, route output to the right project folder.
WhenMedia and URLs. For repo-scoped primary-source research, use the plugin's research skill instead (see section 6).
/last30days30-day multi-source research
WhatSweeps Reddit, X, web, and GitHub for the last 30 days on a topic, producing copy-paste-ready prompts and findings.
When"What's the current state of X" questions where recency matters.
/sharepublish a branded web page
WhatPublishes project content as a branded, deployed web page - ephemeral or permanent.
WhenA customer or teammate needs a link, not a file. (Proposals like Lincoln Center ship this way.)
/export-pipelineObsidian notes to branded output
WhatExports Obsidian notes to PDF, DOCX, or email HTML with Empower branding.
WhenA vault note needs to leave the vault looking professional.
/excalidrawdiagrams in the vault
WhatExcalidraw diagrams as .excalidraw.md files in Obsidian, using Empower brand colors.
WhenA flow or architecture needs a picture that stays editable.
/google-docs-formattingprofessional Google Docs
WhatFormatting standards for professional Google Docs.
WhenA shared gdoc has to look like an adult made it.
/nlmNotebookLM transformations
WhatNotebookLM-powered content transformation: podcasts, slide decks, infographics from source docs.
WhenRepackaging dense material into a listenable or presentable form.
/claude-apibuild with the Claude API / SDK
WhatGuidance for building apps on the Claude API, Anthropic SDKs, or the Agent SDK.
WhenWriting code that calls Claude - agents, tools, batch jobs.
6. Plugin skills: the mattpocock set
25 skills from the mattpocock-skills plugin (upstream: github.com/mattpocock/skills - auto-updates, currently v1.2.x). This is the vertical axis from section 3, plus its supporting cast. Philosophy: small, composable, hackable - the human keeps control; no framework owns your process.
/ask-mattthe router - start here when unsure
WhatMaps every skill and flow and how they connect; tells you which one fits your situation.
WhenYou know there's a right skill but can't remember which.
/grill-with-docssharpening interview, writes docs
WhatRelentless interview about a plan or design. Stateful: writes findings into CONTEXT.md and ADRs as it goes, so the next agent starts smarter.
WhenThe done-condition isn't checkable yet and you're inside a repo with (or that deserves) domain docs.
/grill-mesame interview, no docs
WhatThe same relentless interview as grill-with-docs, but stateless - no files written.
WhenNon-code planning, or thinking that isn't tied to a repo.
/to-specconversation to spec
WhatSynthesizes the current conversation into a spec and publishes it to the repo's tracker. No new questions - pure capture.
WhenRight after a grill, while the decisions are still in context.
/to-ticketsspec to tracer-bullet tickets
WhatSplits a plan or spec into tickets that each cut a narrow, complete, verifiable path through every layer, with explicit blocking edges.
WhenMulti-session builds. In house mode, don't run it unless asked - it would mint a competing board.
/implementbuild one ticket, disciplined
WhatImplements one ticket or spec: drives /tdd internally slice by slice, closes with /code-review before committing.
WhenA ticket is ready and you have a fresh context for it. The default worker prompt in tracked-mode orchestration.
/tddred-green-refactor
WhatTest-driven development, one vertical slice at a time. Usually invoked by /implement, works standalone too.
WhenBuilding features or fixes test-first.
/code-reviewtwo-axis diff review
WhatReviews changes since a fixed point on two axes in parallel subagents: Standards (repo conventions) and Spec (does it match the originating issue).
WhenClosing an implement, reviewing a branch or PR.
/diagnosing-bugsdiscipline for hard bugs
WhatRefuses to theorize until it has a tight feedback loop reproducing red, then minimize, hypothesize, instrument, fix, regression-test. Redacts secrets in captured artifacts.
WhenHard, intermittent, or "impossible" bugs and performance regressions.
/triageexternal issues to agent-ready briefs
WhatMoves externally-raised issues/PRs through a 5-state machine (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix), producing agent-ready briefs.
WhenBug reports and requests raised by other people, not your own tickets.
/wayfindermap work too big for one session
WhatPlans a shared map of decision tickets on the tracker, resolves them one at a time (producing decisions, not code), then hands off to /to-spec once the fog clears.
WhenGreenfield or huge efforts where you can't even spec yet.
/prototypethrowaway that answers a question
WhatBuilds a single shareable HTML file (no build, no server) to answer a design question - state model feel, or several toggleable UI variants. Kept on a prototype/<name> branch.
WhenA design question needs a runnable answer before you commit to a build.
/improve-codebase-architecturefind deepening opportunities
WhatScans a codebase for module-deepening opportunities, presents an HTML report, then grills through whichever candidate you pick.
WhenCodebase health work between features, or after a painful bug hunt.
/setup-matt-pocock-skillsflip a repo to tracked mode
WhatOne-time per-repo setup: picks the issue tracker, triage labels, and domain-doc layout; writes docs/agents/issue-tracker.md + triage-labels.md + domain.md. This file is exactly what /so checks for tracked mode.
WhenOne of our own repos graduates to needing a real tracker. (This is what Kalvin ran on jobflo.)
/domain-modelingpin down the project's language
WhatBuilds and sharpens the project glossary - challenges fuzzy terms, records ADRs, keeps CONTEXT.md current.
WhenTerminology keeps drifting, or before a big design conversation.
/codebase-designdeep-module vocabulary
WhatShared vocabulary for designing deep modules: module, interface, depth, seam, adapter. Other skills speak it.
WhenDesigning a module interface, deciding where a seam goes, making code testable.
researchrepo-scoped primary-source research
WhatDelegates reading legwork to a background agent against primary sources; leaves a cited markdown file in the repo. Feeds grilling with grounded facts.
WhenDocs or API facts need gathering for a build. Note the name collision: house /research is Fabric AI for media/URLs. Pick by job, not name.
/resolving-merge-conflictsmerge conflicts by intent
WhatWorks an in-progress merge/rebase hunk by hunk, tracing each side's intent to its source. Never --abort.
WhenA rebase left you in conflict hell.
/wizardbash wizard for human-only steps
WhatGenerates an interactive bash wizard walking a human through steps only they can do: provisioning, credentials, dashboard clicks, one-off migrations. Opens URLs, captures values, writes .env / secrets.
WhenThe build hits a step that needs your hands, and you want it repeatable for the next person.
grillingthe interview engine (model-invoked)
WhatThe reusable interview primitive under grill-me, grill-with-docs, triage, and wayfinder. You rarely call it directly.
WhenAutomatically, whenever a skill needs to grill you.
writing-for-agentsreference for writing skills and CLAUDE.md
WhatReference for writing documents agents consume: skills, AGENTS.md, CLAUDE.md. Model-invoked when editing those files.
WhenCreating or editing any skill or agent-context file.
/handoffportable context for the next session
WhatCompacts the conversation into a portable markdown handoff doc for a new session, directory, or colleague.
WhenNear the context limit mid-phase - hand off to a fresh session rather than /compact.
/teachmulti-session learning workspace
WhatA teaching workspace that persists across sessions while you learn a concept.
WhenYou want to actually learn something, not just have it done for you.
/to-questionnairemine someone else for decisions
WhatThe inverse of grill-me: interviews you about the send (who it's for, what you need back) and produces a questionnaire for someone else to fill in.
WhenDecisions are blocked on another person's answers - like the definitional questions owed by a stakeholder.
/wait-whatone-word corrective
WhatFire it the instant a response doesn't land - the agent re-pitches the same content using the project's own vocabulary.
WhenYou read a reply twice and it still didn't click.
feature-dev (explorer/architect/reviewer agents), code-review, hookify (turn "never do X again" into enforced hooks), context7 (live library docs), playwright, security-guidance, frontend-design, laravel-boost, github, commit-commands, and the private empower-funding plugin (EnFin packages).7. Memory and brain
Two stores, different jobs, both feeding each other:
MEMORY.md + topic files
Always-loaded index with a rotating "Active focus" list, plus 8 topic folders (profile, feedback, setup, work_empower, projects, reference, ventures, retired), each with its own on-demand index. One markdown file per fact. Fixed token cost no matter how much history piles up.
Semantic search over everything
Supabase + pgvector store queried with brain_search before answering any "did we already decide..." question. Captures typed as thought / learning / decision / project / reference, tagged against a project taxonomy whitelist.
The loop: work happens, /wrap logs it to the project's history.md and captures learnings, /sunday-review compresses the week, /memory-synthesis structures the logs, and corrections become standing rules so mistakes don't repeat. When teaching someone: the habit that matters most is capturing decisions when they happen - everything downstream depends on it.
8. Models and research routing
Model stratification
Use the simplest model that can do the job. This is the biggest cost lever in the whole system.
| Model | Role |
|---|---|
| Fable 5 | Top tier (Mythos-class). Hardest reasoning, highest-stakes plans, boss/checker/verdict roles. Not the everyday default. |
| Opus 5 | The daily driver: architecture, complex multi-file changes, nuanced writing, most real work. |
| Sonnet 5 | Standard subagent work: research, code review, routine development, most delegated tasks. |
| Haiku 4.5 | Mechanical tasks: formatting, simple lookups, file operations. |
Research routing
| Need | Tool |
|---|---|
| Quick factual lookup, reasoning | Grok CLI headless, first choice |
| Deep multi-source research | Grok, then WebSearch |
| Fetch a known page | Firecrawl or WebFetch |
| Video or article processing | /research (Fabric AI) |
| Library and framework docs | context7 plugin |
| Past decisions and history | brain_search - always before re-deciding anything |
Key paths
| Path | What lives there |
|---|---|
~/CLAUDE.md | The global contract - everything in section 2. |
~/.claude/skills/ | All 46 house skills (section 5). |
~/.keys/ | Credential management via keys.py; Keychain-backed. |
~/agent-stack/ | Playbooks (cross-portal browser automations) + portals config. |
~/Herd/ | Laravel projects; ~/Herd/CLAUDE.md auto-loads stack conventions. |
~/Desktop/<project>/ | Project workspaces: CLAUDE.md + .claude/history.md each. |