Briefs Setup

Setup Claude Briefs

Creates the Briefs project management structure in the current project. Briefs is a lightweight system for managing focus across sessions - for both humans and LLMs.

What This Creates

A briefs directory with four files:

• CURRENT.md - The heart of the system. One active task: context, planned approach, task list, session log.
• BACKLOG.md - The larger project plan: up next, blocked, backlog, done.
• PROGRESS.md - The long-term memory. Completed tasks with backstory and decisions. Written only by /briefs-done.
• NOTES.md - Technical notes, gotchas, and references that outlive any single task.

The lifecycle that maintains them: /briefs-plan (settle the approach) → /briefs-work (execute, repeatable sessions) → user reviews and commits → /briefs-done (review against plan, archive, reset). /briefs-health audits when things feel muddled.

Steps

1. Ask where to put the briefs folder

Ask: "Where should I create the briefs folder?"

Present two options:

• With this project - creates .briefs/ in the project root. Suggest adding .briefs/ to .gitignore (these are working notes, not source code).
• Somewhere else - user provides an absolute path. Good for people who keep notes in Obsidian, a shared docs folder, or anywhere outside the repo.

2. Create the directory

mkdir -p <chosen-path>

3. Save the path

Create .claude/briefs-path containing the absolute path to the briefs folder. This lets the other briefs skills find it automatically in future sessions.

mkdir -p .claude
echo "<absolute-path-to-briefs-folder>" > .claude/briefs-path

If .briefs/ was chosen inside the project, store the absolute path anyway for consistency.

4. Create CURRENT.md

The skeleton every skill in the family expects (/briefs-plan fills it, /briefs-work maintains it, /briefs-done archives and resets it):

Working on: **<nothing — pick a task with /briefs-plan>**
Branch: 

# Context

# Approach

# Task list

# Log

# Review notes

If the user already has an active task, offer to fill in Working on: and # Context from their description now — and point them at /briefs-plan for the Approach.

5. Create BACKLOG.md

# Goal
[One sentence: what is this project building/solving?]

---

# Blocked
[Waiting on someone outside the project. Each says who, and since when.]

# Backlog
[Everything that needs doing, roughly ordered — the top few are what matters
next, the rest is a holding pen.]

## One item, as a heading
*tag · optional metadata*

Prose, measurements, links, sub-bullets — whatever the item needs.

# Done
Completed work lives in **PROGRESS.md** — what was built, why, and the commit.
This file is for what is still outstanding.

No # Backlog title at the top. The filename says it, and a # Backlog containing a ## Backlog reads as though one nests inside the other. Sections are #, items are ##.

Items are ## headings, not checkboxes. A backlog item grows: measurements, a settled decision, a correction, the reason something was deferred. Checkbox list items fight that — continuation lines need a hanging indent, and the whole thing renders as one bullet no matter how long it gets. Headings fold in Obsidian, appear in the outline panel, and can be linked to as [[BACKLOG#One item, as a heading]].

The checkbox instinct is right for CURRENT.md's # Task list, where an item really is a thing you tick within one session. It is wrong here, where an item is a small document that may sit for weeks.

Completed items are deleted, not listed. PROGRESS.md already records what was built, when, and with which commit; a # Done list in the backlog is a second copy that drifts. Keep the # Done heading as a one-line pointer so a reader knows where the history went.

Older briefs use - [ ] checkbox items with indented continuation lines. Both shapes are readable; the other briefs skills handle either. Don't convert an existing file just because you are passing through — but do write new items as headings, and keep one file to one style.

6. Create PROGRESS.md

[Completed tasks, newest first. Written by /briefs-done — one foldable entry
per task: `## Task name (YYYY-MM-DD HH:MM)`, commit SHA, what/why, scope, key
decisions, and the fixtures and commands it was tested with.]

No # Progress title, for the same reason BACKLOG.md has none: the filename says it, and a title wrapping every entry makes the entries ### for no gain. Entries are ##, so they are top-level siblings and fold cleanly.

7. Create NOTES.md

# Notes

[Key learnings, gotchas, and reference material]

8. If project-local, offer to gitignore

If the briefs folder is inside the project, check if .gitignore exists and offer to add the folder to it.

9. Confirm completion Show what was created and where it lives. Suggest /briefs-plan to plan the first task (or /briefs-work if there's already a plan to execute).