Keep it brief. A lightweight focus system for working with Claude Code.
Briefs is a set of Claude Code skills that help you and Claude stay focused across sessions. One task at a time, always know the next step.
It works by maintaining a small set of markdown files that act as shared working memory between you and Claude. No database, no app - just files you can keep anywhere (in your repo, in Obsidian, wherever).
Four markdown files:
- CURRENT.md - The heart of it. The one active task: context, the planned approach, a task list, and a session log. Claude reads this at the start of every session.
- BACKLOG.md - The bigger picture. What's blocked, and what's still to do.
- PROGRESS.md - The long-term memory. Completed tasks with backstory, scope, and decisions.
- NOTES.md - Things worth remembering across sessions.
Plus a queue/ folder when you plan ahead - staged plans waiting for the current
task to close.
Six skills, forming a lifecycle:
/briefs-setup- Creates the files. Asks where you want them. Run once per project./briefs-plan- Architect mode. Investigates the codebase (delegating the bulk reading to cheap subagents), settles the open decisions with you, and writes a complete Approach into CURRENT.md - precise enough that a cheaper model can execute it without judgement calls. If CURRENT.md is busy, it stages the plan inqueue/instead./briefs-work- Executor mode. Reads CURRENT.md, works the task list in order, ticks boxes as items are built and verified, logs deviations. It never declares the task done - that's yours./briefs-done- The close-out ceremony, run after you have reviewed and committed. Reviews the diff against the plan, archives to PROGRESS.md, resets CURRENT.md. (It can draft a PR description from the accumulated review notes, but only if you ask.) Also does mid-task checkpoints: hand it a SHA for a finished slice and it writes the PROGRESS entry without closing the task./briefs-health- Audits the briefs when a project feels muddled or stalled, and drives a reprioritization. Structural, not editorial: it asks whether the system is working - are tasks getting closed, is planning happening, is a queue rotting./briefs-groom- Walks BACKLOG.md item by item with you when the list has grown long enough that you skim past it. Verifies what it can against PROGRESS.md and the code - items that shipped but were never removed, titles their own bodies contradict, duplicates - and asks about the rest rather than guessing. It never deletes on its own judgement.
CURRENT.md, mid-task (abridged - # Context and # Review notes omitted):
Working on: **Quote paragraphs → Gutenberg blocks**
Branch: `add/paragraph-builders`
# Approach
## Decisions (settled)
- **`core/pullquote`, not `core/quote`.** Compared both on a scratch page: this
theme renders pullquote large and italic, quote with a left border. The design
calls for the former.
- **Strip the source's outer `<p>` before handing it over.** The block helper
hardcodes its own `<p>` wrapper, and *zero* of the 4,767 source values are
plain text - passing them through unchanged yields `<p><p>…</p></p>` every
time.
# Task list
- [x] Formatter emits `core/pullquote`
- [ ] Trailing attribution extracted into `<cite>` - 1,474 of 4,767 match
# Log
- Blocked at the second gate: `body` is mapped *after* the paragraph field and
overwrites it. 30,269 of 30,410 records affected. Needs a decision before I
continue.The reasons are the point. Without "compared both on a scratch page", the next
session relitigates the choice - and core/quote looks like the obvious pick
from the name alone. The blocker in the log is the other half: the executing
session stopped and wrote down what it found rather than guessing.
The lifecycle maps onto model economics. Planning is decision-dense but token-light - run /briefs-plan on your best model. Execution is token-heavy but decision-light because the plan removed the decisions - run /briefs-work sessions on a cheaper model, in fresh contexts. The review inside /briefs-done is where an expensive model earns its rate again, cheaply: checking a diff against a written plan costs far less than writing the code.
The completion gate is the other half of the design. Work sessions record progress (ticked boxes mean "built and checked"); only /briefs-done records completion, and it refuses to archive code that hasn't been committed - so nothing gets declared finished before a human has actually reviewed it.
The queue/ folder makes the pipeline overlap: plan task N+1 while task N executes. Every plan is stamped with the commit it was planned against, and promotion (by /briefs-done after close-out, or /briefs-work on an empty CURRENT.md) re-verifies the plan's file references against the code as it stands - superficial drift gets fixed inline; structural drift sends the plan back to /briefs-plan instead of letting the executor improvise.
Copy the skill folders into your Claude Code skills directory:
cp -r briefs-* ~/.claude/skills/In any project, run:
/briefs-setup
It'll ask where to put the briefs folder - in the project (.briefs/) or somewhere else (Obsidian vault, shared docs, wherever). Then it creates the files and saves the path so the other skills find it automatically.
The loop for each task:
/briefs-plan # settle approach + decisions, on your strongest model
/briefs-work # execute - as many sessions as needed, any model
# ...you review the diff and commit...
/briefs-done # review vs plan, archive, reset
Small, obvious tasks can skip straight to /briefs-work - the skill knows a typo fix doesn't need an architecture document.
And occasionally, outside the loop:
/briefs-health # when a project feels stalled - is the system working?
/briefs-groom # when the backlog has grown long enough to distrust
LLMs are eager. They'll generate 200 lines of code when you asked a question. They'll refactor things you didn't ask about. And they'll happily declare a task finished before you've reviewed a single line.
Briefs fixes this by giving Claude (and you) a shared sense of "where are we" and "what's next" - and by separating progress (Claude's to record) from completion (yours to grant).
MIT