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. Up next, blocked, backlog, done.
- PROGRESS.md - The long-term memory. Completed tasks with backstory, scope, and decisions.
- NOTES.md - Things worth remembering across sessions.
Five 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. If CURRENT.md is busy, it stages the plan inqueue/instead - so you can plan the next task with a strong model while a cheaper one executes the current task in another session./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, drafts PR notes, archives to PROGRESS.md, resets CURRENT.md. 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.
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-setup briefs-plan briefs-work briefs-done briefs-health ~/.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, PR notes, archive, reset
Small, obvious tasks can skip straight to /briefs-work - the skill knows a typo fix doesn't need an architecture document.
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